@ceralive/modem-control 1.0.0 → 1.2.0

package/src/backend/cell-info.ts

@@ -1,160 +0,0 @@
-// 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 type { EpochMillis } from '../domain';
-import type { DecodedProps } from './managed-objects';
-import { numberProp, stringProp } from './managed-objects';
-
-/** Where a batch of cell readings came from, and when it was observed. */
-export interface CellInfoProvenance {
-	/** A human/source tag, e.g. the modem path or `'Modem.GetCellInfo'`. */
-	readonly source: string;
-	readonly observedAt: EpochMillis;
-}
-
-/** One normalized cell reading — only the pinned fields, plus provenance. */
-export interface CellReading {
-	/** `true` when this dict is marked as the serving cell. */
-	readonly serving: boolean;
-	/** The cell identifier, when supplied (serving-cell tiebreak key). */
-	readonly cellId?: string;
-	/** Physical cell id — from the `physical-ci` key ONLY. */
-	readonly pci?: number;
-	readonly rsrp?: number;
-	readonly rsrq?: number;
-	/** NR SINR — from the `sinr` key ONLY (a `snr`-keyed dict is ignored). */
-	readonly sinr?: number;
-	/** Radio band — present ONLY when the source supplied it directly. */
-	readonly band?: string;
-	readonly source: string;
-	readonly observedAt: EpochMillis;
-}
-
-/** Read a `serving` flag: an explicit `serving` bool, else a `cell-type` naming it. */
-function readServing(cell: DecodedProps): boolean {
-	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: DecodedProps,
-	provenance: CellInfoProvenance,
-): CellReading {
-	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: readonly DecodedProps[],
-	provenance: CellInfoProvenance,
-): readonly CellReading[] {
-	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: CellReading, b: CellReading): number {
-	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: number | undefined, b: number | undefined): number {
-	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<T extends number | string>(a: T | undefined, b: T | undefined): number {
-	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: CellReading): string {
-	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: readonly CellReading[]): CellReading | undefined {
-	if (cells.length === 0) {
-		return undefined;
-	}
-	return cells.reduce((best, cell) => (compareServing(cell, best) < 0 ? cell : best));
-}

package/src/backend/device-classifier.test.ts

@@ -1,168 +0,0 @@
-// The classifier's contract, one fixture per class — plus the HONESTY guarantee: an
-// ambiguous descriptor set returns `unmanaged` with a truthful reason, never a
-// confident guess, and mass storage without a modeswitch trigger is NOT a modem.
-
-import { describe, expect, test } from 'bun:test';
-import { classifyDevice, detectUsbMode, type UsbDeviceSnapshot } from './device-classifier';
-
-/** A Quectel-style QMI composition: a `qmi_wwan` control port (+ AT serials). */
-const QMI: UsbDeviceSnapshot = {
-	vendorId: '2c7c',
-	productId: '0125',
-	model: 'EG25-G',
-	bDeviceClass: 0,
-	interfaces: [
-		{ interfaceClass: 0xff, interfaceSubClass: 0xff, interfaceProtocol: 0xff, driver: 'option' },
-		{ interfaceClass: 0xff, interfaceSubClass: 0xff, interfaceProtocol: 0xff, driver: 'qmi_wwan' },
-	],
-};
-
-/** An MBIM composition: the standard 0x02/0x0e control + 0x0a data pair. */
-const MBIM: UsbDeviceSnapshot = {
-	vendorId: '1199',
-	productId: '9071',
-	model: 'Sierra EM-series',
-	bDeviceClass: 0,
-	interfaces: [
-		{ interfaceClass: 0x02, interfaceSubClass: 0x0e, interfaceProtocol: 0x00, driver: 'cdc_mbim' },
-		{ interfaceClass: 0x0a, interfaceSubClass: 0x00, interfaceProtocol: 0x02, driver: 'cdc_mbim' },
-	],
-};
-
-/** A Huawei HiLink personality: CDC-ECM Ethernet, no control port — firmware, not switchable. */
-const HILINK_ECM: UsbDeviceSnapshot = {
-	vendorId: '12d1',
-	productId: '14db',
-	model: 'HUAWEI HiLink',
-	bDeviceClass: 0x02,
-	interfaces: [
-		{ interfaceClass: 0x02, interfaceSubClass: 0x06, interfaceProtocol: 0x00, driver: 'cdc_ether' },
-		{ interfaceClass: 0x0a, interfaceSubClass: 0x00, interfaceProtocol: 0x00, driver: 'cdc_ether' },
-	],
-};
-
-/** An RNDIS tether: the wireless-RNDIS descriptor, no control port. */
-const RNDIS: UsbDeviceSnapshot = {
-	vendorId: '19d2',
-	productId: '0601',
-	model: 'RNDIS tether',
-	bDeviceClass: 0x00,
-	interfaces: [
-		{
-			interfaceClass: 0xe0,
-			interfaceSubClass: 0x01,
-			interfaceProtocol: 0x03,
-			driver: 'rndis_host',
-		},
-		{
-			interfaceClass: 0x0a,
-			interfaceSubClass: 0x00,
-			interfaceProtocol: 0x00,
-			driver: 'rndis_host',
-		},
-	],
-};
-
-/** A modem in mass-storage installer mode, flagged for usb_modeswitch. */
-const STORAGE_PRE_MODESWITCH: UsbDeviceSnapshot = {
-	vendorId: '12d1',
-	productId: '1f01',
-	model: 'HUAWEI Mobile',
-	bDeviceClass: 0x00,
-	interfaces: [
-		{
-			interfaceClass: 0x08,
-			interfaceSubClass: 0x06,
-			interfaceProtocol: 0x50,
-			driver: 'usb-storage',
-		},
-	],
-	udevProperties: { ID_USB_MODESWITCH: '1' },
-};
-
-/** A composite that matches NO known modem pattern — vendor + HID, no driver. */
-const AMBIGUOUS: UsbDeviceSnapshot = {
-	vendorId: '1234',
-	productId: '5678',
-	model: 'Unknown Composite',
-	bDeviceClass: 0x00,
-	interfaces: [
-		{ interfaceClass: 0x03, interfaceSubClass: 0x00, interfaceProtocol: 0x00 },
-		{ interfaceClass: 0xff, interfaceSubClass: 0x42, interfaceProtocol: 0x01 },
-	],
-};
-
-describe('classifyDevice — the six canonical fixtures', () => {
-	test('QMI composition → mm-managed', () => {
-		expect(classifyDevice(QMI).deviceClass).toBe('mm-managed');
-		expect(detectUsbMode(QMI)).toBe('qmi');
-	});
-
-	test('MBIM composition → mm-managed', () => {
-		const result = classifyDevice(MBIM);
-		expect(result.deviceClass).toBe('mm-managed');
-		expect(result.reason).toContain('MBIM');
-		expect(detectUsbMode(MBIM)).toBe('mbim');
-	});
-
-	test('Huawei HiLink-ECM (firmware personality) → router-mode', () => {
-		const result = classifyDevice(HILINK_ECM);
-		expect(result.deviceClass).toBe('router-mode');
-		expect(result.reason).toContain('ECM');
-		expect(detectUsbMode(HILINK_ECM)).toBe('router-ethernet');
-	});
-
-	test('RNDIS tether → router-mode', () => {
-		const result = classifyDevice(RNDIS);
-		expect(result.deviceClass).toBe('router-mode');
-		expect(result.reason).toContain('RNDIS');
-		expect(detectUsbMode(RNDIS)).toBe('rndis');
-	});
-
-	test('mass-storage before usb_modeswitch → pending-modeswitch (a distinct state)', () => {
-		const result = classifyDevice(STORAGE_PRE_MODESWITCH);
-		expect(result.deviceClass).toBe('pending-modeswitch');
-		expect(result.reason).toContain('usb_modeswitch');
-	});
-
-	test('ambiguous composite → unmanaged, with an HONEST reason (never guessed)', () => {
-		const result = classifyDevice(AMBIGUOUS);
-		expect(result.deviceClass).toBe('unmanaged');
-		expect(result.reason).toContain('vendor-specific');
-		// Never a confident modem/router class.
-		expect(result.deviceClass).not.toBe('mm-managed');
-		expect(result.deviceClass).not.toBe('router-mode');
-	});
-});
-
-describe('classifyDevice — honesty guards', () => {
-	test('mass storage WITHOUT a modeswitch trigger is unmanaged, not pending-modeswitch', () => {
-		const plainDisk: UsbDeviceSnapshot = {
-			vendorId: '0781',
-			productId: '5567',
-			model: 'SanDisk Cruzer',
-			bDeviceClass: 0x00,
-			interfaces: [
-				{
-					interfaceClass: 0x08,
-					interfaceSubClass: 0x06,
-					interfaceProtocol: 0x50,
-					driver: 'usb-storage',
-				},
-			],
-		};
-		const result = classifyDevice(plainDisk);
-		expect(result.deviceClass).toBe('unmanaged');
-		expect(result.reason).toContain('usb_modeswitch');
-	});
-
-	test('a bare vendor interface with no driver is NOT assumed to be a QMI modem', () => {
-		const bareVendor: UsbDeviceSnapshot = {
-			vendorId: '2357',
-			productId: '0001',
-			bDeviceClass: 0x00,
-			interfaces: [{ interfaceClass: 0xff, interfaceSubClass: 0x00, interfaceProtocol: 0x00 }],
-		};
-		expect(classifyDevice(bareVendor).deviceClass).toBe('unmanaged');
-	});
-});

package/src/backend/device-classifier.ts

@@ -1,248 +0,0 @@
-// 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.
-
-import type { CanonicalUsbMode, ExpectedDescriptors } from '../usb-mode';
-
-/** One USB interface's descriptor bytes plus its bound kernel driver, if any. */
-export interface UsbInterface {
-	readonly interfaceClass: number;
-	readonly interfaceSubClass: number;
-	readonly interfaceProtocol: number;
-	/** The bound kernel driver (`qmi_wwan`, `cdc_mbim`, `option`, `cdc_ether`, …). */
-	readonly driver?: string;
-}
-
-/** A single USB device as observed from udev/sysfs — the classifier's whole input. */
-export interface UsbDeviceSnapshot {
-	readonly vendorId: string;
-	readonly productId: string;
-	readonly model?: string;
-	readonly firmwareRevision?: string;
-	/** The device-descriptor `bDeviceClass` byte (0 ⇒ class is per-interface). */
-	readonly bDeviceClass: number;
-	readonly interfaces: readonly UsbInterface[];
-	/** Stable physical-topology UID (udev `ID_PATH` / physdev) — survives a mode change. */
-	readonly physicalUid?: string;
-	/** The bound network interface name, if the device presents one (`wwan0`, `usb0`). */
-	readonly ifname?: string;
-	/** Raw udev properties (`ID_USB_MODESWITCH`, `ID_MM_CANDIDATE`, …). */
-	readonly udevProperties?: Readonly<Record<string, string>>;
-}
-
-/** The four device classes. `pending-modeswitch` is distinct from `unmanaged`. */
-export type DeviceClass = 'mm-managed' | 'router-mode' | 'unmanaged' | 'pending-modeswitch';
-
-/** A classification plus a human-readable reason (always populated). */
-export interface DeviceClassification {
-	readonly deviceClass: DeviceClass;
-	readonly reason: string;
-}
-
-// USB-IF class / subclass / protocol codes used below.
-const CLASS_COMM = 0x02; // CDC communications (control interface)
-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: ReadonlySet<string> = new Set(['qmi_wwan']);
-const AT_DRIVERS: ReadonlySet<string> = new Set(['option', 'qcserial', 'cdc_acm']);
-const ECM_NCM_DRIVERS: ReadonlySet<string> = new Set(['cdc_ether', 'cdc_ncm']);
-const RNDIS_DRIVERS: ReadonlySet<string> = new Set(['rndis_host']);
-const STORAGE_DRIVERS: ReadonlySet<string> = new Set(['usb-storage', 'uas']);
-
-function isMbimControl(i: UsbInterface): boolean {
-	return i.interfaceClass === CLASS_COMM && i.interfaceSubClass === SUB_MBIM;
-}
-
-function isQmiControl(i: UsbInterface): boolean {
-	return i.interfaceClass === CLASS_VENDOR && i.driver !== undefined && QMI_DRIVERS.has(i.driver);
-}
-
-function isAtControl(i: UsbInterface): boolean {
-	// 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: UsbInterface): boolean {
-	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: UsbInterface): boolean {
-	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: UsbInterface): boolean {
-	if (i.interfaceClass === CLASS_MASS_STORAGE) {
-		return true;
-	}
-	return i.driver !== undefined && STORAGE_DRIVERS.has(i.driver);
-}
-
-function isVendorSpecific(i: UsbInterface): boolean {
-	return i.interfaceClass === CLASS_VENDOR;
-}
-
-function controlKind(i: UsbInterface): string {
-	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: UsbDeviceSnapshot): boolean {
-	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: UsbDeviceSnapshot, hasStorage: boolean): string {
-	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: UsbDeviceSnapshot): DeviceClassification {
-	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) };
-}
-
-/**
- * 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: UsbDeviceSnapshot): CanonicalUsbMode | undefined {
-	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: UsbDeviceSnapshot,
-	expected: ExpectedDescriptors,
-): boolean {
-	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/src/backend/enrichment.ts

@@ -1,96 +0,0 @@
-// 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 type { CellReading } from './cell-info';
-import { selectServingCell } from './cell-info';
-import { MODEM_IFACE, SIM_IFACE } from './constants';
-import type { DecodedManagedObjects } from './managed-objects';
-import { findInterface, followObjectPath, numberProp, stringProp } from './managed-objects';
-import type { SignalCadence } from './signal-setup';
-
-/** 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;
-}
-
-/** MMSimType (`Sim.SimType`) → the domain `SimType`. */
-function mapSimType(value: number | undefined): SimType {
-	switch (value) {
-		case 1:
-			return 'physical';
-		case 2:
-			return 'esim';
-		default:
-			return 'unknown';
-	}
-}
-
-/** MMSimEsimStatus (`Sim.EsimStatus`) → the domain `EsimStatus`. */
-function mapEsimStatus(value: number | undefined): EsimStatus {
-	switch (value) {
-		case 1:
-			return 'no-profiles';
-		case 2:
-			return 'with-profiles';
-		default:
-			return 'unknown';
-	}
-}
-
-/** Read `Modem.Revision`, when present. */
-export function readRevision(tree: DecodedManagedObjects, modemPath: string): string | undefined {
-	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: DecodedManagedObjects, modemPath: string): EsimInfo {
-	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: DecodedManagedObjects,
-	modemPath: string,
-	signalCadence: SignalCadence,
-	cellInfo: readonly CellReading[],
-): ModemEnrichment {
-	const revision = readRevision(tree, modemPath);
-	const serving = selectServingCell(cellInfo);
-	return {
-		...(revision !== undefined ? { revision } : {}),
-		esim: readEsimInfo(tree, modemPath),
-		signalCadence,
-		cellInfo,
-		...(serving !== undefined ? { servingCell: serving } : {}),
-	};
-}