@ceralive/modem-control 1.2.0 → 1.3.0

package/README.md

@@ -173,6 +173,11 @@ represented return path. Its suppression vocabulary is `unknown-vendor`,
 no targets. Unknown/disabled/blocked decisions happen before transport contact, and a
 capability read sends only the named READ/TEST forms, never a SET.
 
+The current and enumeration replies must both carry a successful AT result before their raw
+bodies are parsed. If either query fails, the operation returns the existing `no-return-path`
+suppression with an empty offer; parseable-looking data followed by `ERROR` cannot make a
+disruptive target writable.
+
 A reviewed catalog transition still provides the strongest success proof: canonical mode
 and USB descriptors must both match. Without one, the weaker fallback proof is the
 re-enumerated device's own post-switch READ reporting the target. AT `OK` is never success.
@@ -194,6 +199,85 @@ are, so the preferred mode and the measurement-recency flag survive normalizatio
 `NormalizedSignal.qualityRecent` claims that flag, and the router sources answer
 `unsupported` for it.
 
+### Extended signal — the `Modem.Signal` per-RAT dicts
+
+`rsrp`, `rsrq`, `snr` and `sinr` are claimed for MM-managed modems from the
+`Modem.Signal` interface's own `a{sv}` properties, so a ModemManager device reports the
+same detail a Huawei or ZTE dongle always did. `rsrp` / `rsrq` / `snr` read `Nr5g` first
+and `Lte` second — on a 5G NSA attach both are populated with different measurements, so
+`MetricProvenance.rawFields` names the dict that answered (`Signal.Nr5g.rsrp`) rather than
+merging the two. `dbm` reads `rssi` across `Lte → Umts → Gsm → Evdo → Cdma`.
+
+`sinr` comes from the `Evdo` dict and from no other, because that is the only dict
+ModemManager defines it on; `Lte` and `Nr5g` publish `snr`, a different quantity that
+never populates it. An LTE/5G modem reporting no SINR therefore answers `not-reported` —
+a claim about this read — and not `unsupported`, which would be a false claim about the
+source. An exported-but-silent `Modem.Signal` yields `not-reported` for every extended
+metric and a modem without the interface yields `not-observed`; neither ever yields a
+zero. Every member the normalized model has no slot for (`error-rate`, `ecio`, `io`,
+`rscp`) stays verbatim in the diagnostics block.
+
+The `Signal.Setup` reporting rate is injectable — `signalIntervalSeconds` on
+`createModemManagerProvider`, on `createMmDbusBackend`, or `intervalSeconds` on
+`SignalSetupManager` — and defaults to `DEFAULT_SIGNAL_INTERVAL_SECONDS` (5 seconds) at
+each. `Setup` takes an unsigned integer, so a fractional or non-positive rate is refused
+at construction rather than marshalled.
+
+### Registration and cell context
+
+`NormalizedRadio` carries `operatorName` and `operatorCode`, and every observation carries
+an additive `cell` block (`cellId` + `tac`). Both operator fields come from
+`Modem3gpp` — the operator the modem is **registered with** — and never from
+`Sim.OperatorName`, which is the *home* operator written into the SIM and differs for the
+whole time a device is roaming. `operatorCode` stays text: the MNC is two or three digits
+and the width is significant, so `31001` and `310001` are different networks.
+
+`cellId` and `tac` come from the existing `3gpp-lac-ci` location source, whose value is one
+five-token string (`MCC,MNC,LAC,CI,TAC`, the last three in uppercase hex). Both fields are
+read out of that single value, so they always describe the same reported cell; a value in
+any other shape reads `malformed` for both rather than being partially decoded, and the hex
+is kept as text so an identifier matches what `mmcli` shows. This is **coarse cell context,
+not a GNSS fix** — it carries no coordinate, `3gpp-lac-ci` is not a member of
+`GNSS_SOURCES`, and nothing on this path enables a location source or sets
+`Location.Setup`'s `signal_location`.
+
+Because ModemManager masks the `Location` property unless `signal_location` is true — which
+this package never sets — nothing populates the optional `location` input today, and an MM
+observation honestly reads `not-observed` for `cell`. Cell identity that is wired comes from
+`Modem.GetCellInfo`, where `CellReading` now also reports `tac` and reads ModemManager's real
+`ci` key (with the older `cell-id` spelling kept as a fallback).
+
+**No EARFCN is claimed.** ModemManager exposes no generic ARFCN; the only occurrences are
+inside per-cell `GetCellInfo` dicts under two different keys for two different quantities —
+`earfcn` for LTE and `nrarfcn` for 5GNR. One normalized field would have to merge them or
+pick a RAT, so neither `NormalizedCell` nor `CellReading` claims one and the raw keys stay
+available.
+
+Router sources claim only what their migrated parsers already decode: ZTE reports the
+operator name and its cell id, UFI reports its cell id, HiLink reports neither. No router
+source derives an operator code from separate unpadded MCC/MNC fields, and `tac` reads
+`not-reported` rather than `unsupported` — nothing here decodes one, which says nothing
+about what the firmware could report.
+
+### Data-usage throughput — absent is not zero
+
+`SlotUsageSnapshot.rateBytesPerSecond` reports throughput over the last **measured**
+sampling interval, and the key is **omitted** rather than set to `0` whenever there was no
+interval to measure. That happens on a first sample, a rebaseline, a paused (ambiguous
+identity) slot, a remap or reboot, an interface missing from `/proc/net/dev`, a clock that
+did not advance — and, most importantly, on a **counter reset**.
+
+Interface counters restart at zero when the interface is re-created. Clamping the resulting
+negative delta to zero would show an idle link that was in fact carrying traffic, and using
+the raw post-reset value would show every byte since the interface came up as if it moved
+inside one interval. So a backwards counter reports **no rate at all**, and the baseline is
+rebased in the same pass so the *next* interval is measured correctly rather than inheriting
+the gap.
+
+Rates are never persisted. A same-boot reload resumes the counter baseline — a cumulative
+total is still true after a restart — but the rate restarts unmeasured, because this process
+did not observe the start of that interval.
+
 ### Mutation safety ports
 
 The root export includes `MutationAdmissionPort`, `ResourceOwnershipPort`,

package/dist/backend/cell-info.d.ts

@@ -12,6 +12,8 @@ export interface CellReading {
     readonly serving: boolean;
     /** The cell identifier, when supplied (serving-cell tiebreak key). */
     readonly cellId?: string;
+    /** Tracking-area code — from the `tac` key ONLY, never derived from the cell id. */
+    readonly tac?: string;
     /** Physical cell id — from the `physical-ci` key ONLY. */
     readonly pci?: number;
     readonly rsrp?: number;

package/dist/backend/cell-info.js

@@ -8,11 +8,24 @@
 //   - `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)
+//   - `ci`, else `cell-id`       the cell identifier (serving-cell tiebreak)
+//   - `tac`                      the tracking-area code, when the RAT reports one
 //   - `band`                     surfaced ONLY when the source supplies it directly;
 //                                never inferred from earfcn / frequency / anything.
 //   - `serving` / `cell-type`    whether this is the serving cell.
 //
+// `ci` IS THE REAL MM KEY and `cell-id` is the fallback, not the other way round.
+// ModemManager 1.24.2 spells it `PROPERTY_CI "ci"` in both `libmm-glib/mm-cell-info-lte.c`
+// and `mm-cell-info-nr5g.c`; `cell-id` is kept behind it so a source that already
+// flattened to that older spelling still decodes rather than silently losing its id.
+//
+// NO ARFCN IS READ HERE, and that is deliberate rather than pending. MM does publish
+// one — but under TWO different keys for two different quantities: `earfcn` in an LTE
+// cell dict and `nrarfcn` in a 5GNR one. There is no generic ARFCN property anywhere on
+// the `Modem`, `Modem3gpp` or `Location` interfaces, so a single `earfcn` field on this
+// reading would have to either merge the two or quietly pick a RAT. `CellReading` makes
+// no ARFCN claim instead, and an unread key stays available to a caller that needs it.
+//
 // 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';
@@ -27,7 +40,8 @@ function readServing(cell) {
 }
 /** 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 cellId = stringProp(cell, 'ci') ?? stringProp(cell, 'cell-id');
+    const tac = stringProp(cell, 'tac');
     const pci = numberProp(cell, 'physical-ci');
     const rsrp = numberProp(cell, 'rsrp');
     const rsrq = numberProp(cell, 'rsrq');
@@ -38,6 +52,7 @@ export function normalizeCellReading(cell, provenance) {
     return {
         serving: readServing(cell),
         ...(cellId !== undefined ? { cellId } : {}),
+        ...(tac !== undefined ? { tac } : {}),
         ...(pci !== undefined ? { pci } : {}),
         ...(rsrp !== undefined ? { rsrp } : {}),
         ...(rsrq !== undefined ? { rsrq } : {}),
@@ -105,6 +120,7 @@ function stableTag(reading) {
     return JSON.stringify([
         reading.serving,
         reading.cellId ?? null,
+        reading.tac ?? null,
         reading.pci ?? null,
         reading.rsrp ?? null,
         reading.rsrq ?? null,

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

@@ -13,6 +13,61 @@ export interface UsbNetClassification {
     readonly deviceClass: UsbNetClass;
     readonly reason: string;
 }
+export type CellularModelEvidenceTier = 'modemmanager-1.24.2-fcc' | 'mainline-kernel' | 'usb-ids-registry';
+/**
+ * A POSITIVE, sourced claim that a labelled family is a router appliance whose only
+ * control surface is a vendor web UI — no ModemManager plugin, no kernel modem driver
+ * claiming its application PID. ABSENCE OF THIS FIELD IS NOT A CLAIM: it does not say
+ * a family is a modem module, only that nothing here asserts otherwise. Same tri-state
+ * discipline as `fcc/coverage.ts` — `unknown` is never folded into `absent`.
+ *
+ * It also does not, and must not, decide a DEVICE CLASS. `classifyDevice` reads live
+ * interfaces and bound drivers; this label is model-family evidence sitting beside it.
+ */
+export type CellularModelFamilyKind = 'router-webui';
+export interface CellularModelEvidence {
+    readonly vendor: string;
+    readonly family: string;
+    readonly evidenceTier: CellularModelEvidenceTier;
+    readonly familyKind?: CellularModelFamilyKind;
+}
+/** Where each evidence tier's rows were read from, so a reviewer can re-check them. */
+export declare const CELLULAR_MODEL_EVIDENCE_SOURCES: {
+    readonly 'modemmanager-1.24.2-fcc': {
+        readonly source: 'ModemManager 1.24.2 data/dispatcher-fcc-unlock/meson.build';
+        readonly pin: 'f2b9ab1ad78d322f32134a444b5b54c6e8160e19';
+    };
+    readonly 'mainline-kernel': {
+        readonly source: 'Linux drivers/net/usb/qmi_wwan.c + drivers/usb/serial/option.c';
+        readonly pin: '45c13f3f9e3bb15fd89ff2864c6f627a3b4b4229';
+    };
+    readonly 'usb-ids-registry': {
+        readonly source: 'The USB ID Repository (linux-usb.org/usb.ids)';
+        readonly pin: '2026.06.26';
+    };
+};
+/**
+ * Exact model-family evidence. This table may label a known VID:PID, but it never
+ * decides whether the device is MM-managed: live interface/driver evidence below
+ * remains authoritative. The pinned ModemManager FCC map is the strongest tier;
+ * `mainline-kernel` rows are application-mode PIDs named by Linux's own qmi_wwan /
+ * qcserial / option device tables; `usb-ids-registry` is the weakest and is used only
+ * where NO kernel modem driver claims the id at all — which is itself the evidence
+ * that the device is a router appliance rather than a controllable module.
+ *
+ * EVERY ROW IS AN EXACT VID:PID. A vendor range is never inferred, and that is not a
+ * stylistic preference: NETGEAR's `0846` and u-blox's `1546` both carry non-cellular
+ * products (Wi-Fi/Ethernet adapters and GNSS receivers respectively), so a
+ * vendor-keyed rule on either would label hardware that has no radio.
+ */
+export declare const CELLULAR_USB_MODEL_ROWS: ReadonlyMap<string, CellularModelEvidence>;
+/**
+ * Vendor ids whose ENTIRE USB range is cellular, so the vendor id alone is honest
+ * evidence of a radio. Membership is a claim about the whole range, which is why
+ * NETGEAR's `0846` is deliberately ABSENT despite having a row above: the USB ID
+ * Repository lists that vendor's Wi-Fi and Ethernet adapters under it, so a
+ * vendor-keyed rule there would report a Wi-Fi dongle as a cellular uplink.
+ */
 export declare const CELLULAR_USB_VENDOR_IDS: ReadonlyMap<string, string>;
 /**
  * Classify one USB device from its udev/sysfs snapshot. Precedence:
@@ -23,6 +78,7 @@ export declare const CELLULAR_USB_VENDOR_IDS: ReadonlyMap<string, string>;
  */
 export declare function classifyDevice(snapshot: UsbDeviceSnapshot): DeviceClassification;
 export declare function cellularVendorName(vendorId: string): string | undefined;
+export declare function cellularModelEvidence(device: Pick<UsbDeviceSnapshot, 'vendorId' | 'productId'>): CellularModelEvidence | undefined;
 export declare function cellularEvidence(device: UsbDeviceSnapshot): string | undefined;
 export declare function classifyUsbNetDevice(device: UsbDeviceSnapshot): UsbNetClassification;
 export declare function publishesGenericIdentity(device: UsbDeviceSnapshot): boolean;

package/dist/backend/device-classifier.js

@@ -35,6 +35,90 @@ 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']);
+/** Where each evidence tier's rows were read from, so a reviewer can re-check them. */
+export const CELLULAR_MODEL_EVIDENCE_SOURCES = {
+    'modemmanager-1.24.2-fcc': {
+        source: 'ModemManager 1.24.2 data/dispatcher-fcc-unlock/meson.build',
+        pin: 'f2b9ab1ad78d322f32134a444b5b54c6e8160e19',
+    },
+    'mainline-kernel': {
+        source: 'Linux drivers/net/usb/qmi_wwan.c + drivers/usb/serial/option.c',
+        pin: '45c13f3f9e3bb15fd89ff2864c6f627a3b4b4229',
+    },
+    'usb-ids-registry': {
+        source: 'The USB ID Repository (linux-usb.org/usb.ids)',
+        pin: '2026.06.26',
+    },
+};
+/**
+ * Exact model-family evidence. This table may label a known VID:PID, but it never
+ * decides whether the device is MM-managed: live interface/driver evidence below
+ * remains authoritative. The pinned ModemManager FCC map is the strongest tier;
+ * `mainline-kernel` rows are application-mode PIDs named by Linux's own qmi_wwan /
+ * qcserial / option device tables; `usb-ids-registry` is the weakest and is used only
+ * where NO kernel modem driver claims the id at all — which is itself the evidence
+ * that the device is a router appliance rather than a controllable module.
+ *
+ * EVERY ROW IS AN EXACT VID:PID. A vendor range is never inferred, and that is not a
+ * stylistic preference: NETGEAR's `0846` and u-blox's `1546` both carry non-cellular
+ * products (Wi-Fi/Ethernet adapters and GNSS receivers respectively), so a
+ * vendor-keyed rule on either would label hardware that has no radio.
+ */
+export const CELLULAR_USB_MODEL_ROWS = new Map([
+    [
+        '03f0:4e1d',
+        { vendor: 'Sierra Wireless', family: 'EM74xx', evidenceTier: 'modemmanager-1.24.2-fcc' },
+    ],
+    ['1199:9071', { vendor: 'Sierra Wireless', family: 'EM74xx', evidenceTier: 'mainline-kernel' }],
+    [
+        '1199:9079',
+        { vendor: 'Sierra Wireless', family: 'EM74xx', evidenceTier: 'modemmanager-1.24.2-fcc' },
+    ],
+    ['1199:907b', { vendor: 'Sierra Wireless', family: 'EM74xx', evidenceTier: 'mainline-kernel' }],
+    ['1199:9091', { vendor: 'Sierra Wireless', family: 'EM75xx', evidenceTier: 'mainline-kernel' }],
+    ['1199:90d3', { vendor: 'Sierra Wireless', family: 'EM919x', evidenceTier: 'mainline-kernel' }],
+    ['1199:c081', { vendor: 'Sierra Wireless', family: 'EM75xx', evidenceTier: 'mainline-kernel' }],
+    [
+        '413c:81a3',
+        { vendor: 'Sierra Wireless', family: 'EM74xx', evidenceTier: 'modemmanager-1.24.2-fcc' },
+    ],
+    [
+        '413c:81a8',
+        { vendor: 'Sierra Wireless', family: 'EM74xx', evidenceTier: 'modemmanager-1.24.2-fcc' },
+    ],
+    ['1bc7:1031', { vendor: 'Telit', family: 'LE910C1-EUX', evidenceTier: 'mainline-kernel' }],
+    ['1bc7:1034', { vendor: 'Telit', family: 'LE910C4-WWX', evidenceTier: 'mainline-kernel' }],
+    ['1bc7:1040', { vendor: 'Telit', family: 'LE922A', evidenceTier: 'mainline-kernel' }],
+    ['1bc7:1050', { vendor: 'Telit', family: 'FN980', evidenceTier: 'mainline-kernel' }],
+    ['1bc7:1060', { vendor: 'Telit', family: 'LN920', evidenceTier: 'mainline-kernel' }],
+    ['1bc7:1070', { vendor: 'Telit', family: 'FN990A', evidenceTier: 'mainline-kernel' }],
+    ['1bc7:1080', { vendor: 'Telit', family: 'FE990A', evidenceTier: 'mainline-kernel' }],
+    ['1bc7:10a0', { vendor: 'Telit', family: 'FN920C04', evidenceTier: 'mainline-kernel' }],
+    ['1bc7:1100', { vendor: 'Telit', family: 'ME910', evidenceTier: 'mainline-kernel' }],
+    ['1bc7:1200', { vendor: 'Telit', family: 'LE920', evidenceTier: 'mainline-kernel' }],
+    ['1546:1311', { vendor: 'u-blox', family: 'LARA-R6', evidenceTier: 'mainline-kernel' }],
+    ['1546:1312', { vendor: 'u-blox', family: 'LARA-R6', evidenceTier: 'mainline-kernel' }],
+    ['1546:1313', { vendor: 'u-blox', family: 'LARA-R6', evidenceTier: 'mainline-kernel' }],
+    ['1546:1341', { vendor: 'u-blox', family: 'LARA-L6', evidenceTier: 'mainline-kernel' }],
+    ['1546:1342', { vendor: 'u-blox', family: 'LARA-L6', evidenceTier: 'mainline-kernel' }],
+    ['1546:1343', { vendor: 'u-blox', family: 'LARA-L6', evidenceTier: 'mainline-kernel' }],
+    [
+        '0846:68e1',
+        {
+            vendor: 'NETGEAR',
+            family: 'LB1120',
+            evidenceTier: 'usb-ids-registry',
+            familyKind: 'router-webui',
+        },
+    ],
+]);
+/**
+ * Vendor ids whose ENTIRE USB range is cellular, so the vendor id alone is honest
+ * evidence of a radio. Membership is a claim about the whole range, which is why
+ * NETGEAR's `0846` is deliberately ABSENT despite having a row above: the USB ID
+ * Repository lists that vendor's Wi-Fi and Ethernet adapters under it, so a
+ * vendor-keyed rule there would report a Wi-Fi dongle as a cellular uplink.
+ */
 export const CELLULAR_USB_VENDOR_IDS = new Map([
     ['05c6', 'Qualcomm'],
     ['0af0', 'Option'],
@@ -43,6 +127,7 @@ export const CELLULAR_USB_VENDOR_IDS = new Map([
     ['1546', 'u-blox'],
     ['19d2', 'ZTE'],
     ['1bbb', 'TCL/Alcatel'],
+    ['1bc7', 'Telit'],
     ['1c9e', 'Longcheer'],
     ['1e0e', 'SIMCom'],
     ['2c7c', 'Quectel'],
@@ -154,6 +239,9 @@ export function classifyDevice(snapshot) {
 export function cellularVendorName(vendorId) {
     return CELLULAR_USB_VENDOR_IDS.get(vendorId.toLowerCase());
 }
+export function cellularModelEvidence(device) {
+    return CELLULAR_USB_MODEL_ROWS.get(`${device.vendorId}:${device.productId}`.toLowerCase());
+}
 export function cellularEvidence(device) {
     const vendor = cellularVendorName(device.vendorId);
     if (vendor !== undefined)

package/dist/backend/mm-mutations/bands.d.ts

@@ -0,0 +1,4 @@
+import type { BandReadResult, ModemRef, Receipt } from '../../ports/index.js';
+import type { MmMutationContext } from './context.js';
+export declare function readBands(context: MmMutationContext, modem: ModemRef): Promise<BandReadResult>;
+export declare function setCurrentBands(context: MmMutationContext, modem: ModemRef, bands: readonly string[]): Promise<Receipt>;

package/dist/backend/mm-mutations/bands.js

@@ -0,0 +1,49 @@
+import { decodeBandList, encodeBandList, isResetSelection } from '../../band/index.js';
+import { receipt } from '../../ports/index.js';
+import { MODEM_IFACE } from '../constants.js';
+import { fetchManagedObjects, findInterface, propValue } from '../managed-objects.js';
+import { describeMutationError } from './context.js';
+export async function readBands(context, modem) {
+    try {
+        const tree = await fetchManagedObjects(context.transport, context.destination);
+        const props = findInterface(tree, modem, MODEM_IFACE);
+        if (props === undefined) {
+            return { ok: false, reason: 'the modem exports no Modem interface' };
+        }
+        return {
+            ok: true,
+            bands: {
+                supported: decodeBandList(propValue(props, 'SupportedBands')),
+                current: decodeBandList(propValue(props, 'CurrentBands')),
+            },
+        };
+    }
+    catch (error) {
+        return { ok: false, reason: `reading bands failed: ${describeMutationError(error)}` };
+    }
+}
+export function setCurrentBands(context, modem, bands) {
+    if (bands.length === 0) {
+        return Promise.resolve(receipt('band', 'failed', 'no bands were requested'));
+    }
+    const encoded = encodeBandList(bands);
+    if (!encoded.ok) {
+        return Promise.resolve(receipt('band', 'unsupported', `this build does not know the band "${encoded.unknown}"`));
+    }
+    return context.actor.runQuiesced({ stableKey: context.resolveStableKey(modem) }, async () => {
+        try {
+            await context.transport.callMethod({
+                destination: context.destination,
+                path: modem,
+                interface: MODEM_IFACE,
+                member: 'SetCurrentBands',
+                signature: 'au',
+                args: [encoded.values],
+            });
+            return receipt('band', 'applied', isResetSelection(bands) ? 'band lock released' : `bands set to ${bands.join(', ')}`);
+        }
+        catch (error) {
+            return receipt('band', 'failed', `SetCurrentBands failed: ${describeMutationError(error)}`);
+        }
+    });
+}

package/dist/backend/mm-mutations/context.d.ts

@@ -0,0 +1,10 @@
+import type { ModemRef } from '../../ports/index.js';
+import type { DbusTransport } from '../../transport/index.js';
+import type { ModemActor } from '../modem-actor.js';
+export interface MmMutationContext {
+    readonly transport: DbusTransport;
+    readonly actor: ModemActor;
+    readonly destination: string;
+    readonly resolveStableKey: (modem: ModemRef) => string;
+}
+export declare function describeMutationError(error: unknown): string;

package/dist/backend/mm-mutations/context.js

@@ -0,0 +1,3 @@
+export function describeMutationError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/backend/mm-mutations/inhibit.d.ts

@@ -0,0 +1,4 @@
+import type { InhibitLease } from '../../ports/index.js';
+import type { MmMutationContext } from './context.js';
+export declare function inhibitDevice(context: MmMutationContext, uid: string, now: () => number): Promise<InhibitLease>;
+export declare function uninhibitDevice(context: MmMutationContext, lease: InhibitLease): Promise<void>;

package/dist/backend/mm-mutations/inhibit.js

@@ -0,0 +1,19 @@
+import { epochMillis } from '../../domain/index.js';
+import { MM_MANAGER_IFACE, MM_ROOT_PATH } from '../constants.js';
+export async function inhibitDevice(context, uid, now) {
+    await setInhibited(context, uid, true);
+    return { uid, acquiredAt: epochMillis(now()) };
+}
+export async function uninhibitDevice(context, lease) {
+    await setInhibited(context, lease.uid, false);
+}
+function setInhibited(context, uid, inhibit) {
+    return context.transport.callMethod({
+        destination: context.destination,
+        path: MM_ROOT_PATH,
+        interface: MM_MANAGER_IFACE,
+        member: 'InhibitDevice',
+        signature: 'sb',
+        args: [uid, inhibit],
+    });
+}

package/dist/backend/mm-mutations/modes.d.ts

@@ -0,0 +1,5 @@
+import type { DesiredRadio } from '../../domain/index.js';
+import type { ModemRef, Receipt } from '../../ports/index.js';
+import type { MmMutationContext } from './context.js';
+export declare function setRadioModes(context: MmMutationContext, modem: ModemRef, preference: DesiredRadio): Promise<Receipt>;
+export declare function setModeCombination(context: MmMutationContext, modem: ModemRef, allowed: number, preferred: number): Promise<Receipt>;

package/dist/backend/mm-mutations/modes.js

@@ -0,0 +1,44 @@
+import { receipt } from '../../ports/index.js';
+import { MODEM_IFACE } from '../constants.js';
+import { describeMutationError } from './context.js';
+const MODE_BIT = { gsm: 2, umts: 4, lte: 8, '5gnr': 16 };
+export function setRadioModes(context, modem, preference) {
+    const allowed = maskOf(preference.allowedSet ?? new Set(preference.preferenceOrdered));
+    const preferred = preference.preferenceOrdered[0];
+    const preferredMask = preferred !== undefined ? MODE_BIT[preferred] : 0;
+    if (allowed === 0) {
+        return Promise.resolve(receipt('radio', 'failed', 'no radio modes were requested'));
+    }
+    return setModeMasks(context, modem, allowed, preferredMask, 'radio mode preference applied');
+}
+export function setModeCombination(context, modem, allowed, preferred) {
+    if (allowed === 0) {
+        return Promise.resolve(receipt('radio', 'failed', 'no radio modes were requested'));
+    }
+    return setModeMasks(context, modem, allowed, preferred, 'radio mode combination applied');
+}
+function setModeMasks(context, modem, allowed, preferred, successMessage) {
+    return context.actor.runQuiesced({ stableKey: context.resolveStableKey(modem) }, async () => {
+        try {
+            await context.transport.callMethod({
+                destination: context.destination,
+                path: modem,
+                interface: MODEM_IFACE,
+                member: 'SetCurrentModes',
+                signature: '(uu)',
+                args: [[allowed, preferred]],
+            });
+            return receipt('radio', 'applied', successMessage);
+        }
+        catch (error) {
+            return receipt('radio', 'failed', `SetCurrentModes failed: ${describeMutationError(error)}`);
+        }
+    });
+}
+function maskOf(rats) {
+    let mask = 0;
+    for (const rat of rats) {
+        mask |= MODE_BIT[rat];
+    }
+    return mask;
+}

package/dist/backend/mm-mutations/scan.d.ts

@@ -0,0 +1,3 @@
+import type { ModemRef, NetworkScanResult } from '../../ports/index.js';
+import type { MmMutationContext } from './context.js';
+export declare function scanNetworks(context: MmMutationContext, modem: ModemRef, timeoutMs: number): Promise<NetworkScanResult>;

package/dist/backend/mm-mutations/scan.js

@@ -0,0 +1,46 @@
+import { MODEM3GPP_IFACE } from '../constants.js';
+import { numberProp, stringProp } from '../managed-objects.js';
+import { describeMutationError } from './context.js';
+const AVAILABILITY = {
+    0: 'unknown',
+    1: 'available',
+    2: 'current',
+    3: 'forbidden',
+};
+export function scanNetworks(context, modem, timeoutMs) {
+    return context.actor.run(context.resolveStableKey(modem), async () => {
+        try {
+            const reply = await context.transport.callMethod({
+                destination: context.destination,
+                path: modem,
+                interface: MODEM3GPP_IFACE,
+                member: 'Scan',
+                timeoutMs,
+            });
+            return { ok: true, networks: parseScan(reply.body[0]) };
+        }
+        catch (error) {
+            return { ok: false, reason: `network scan failed: ${describeMutationError(error)}` };
+        }
+    });
+}
+function parseScan(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const networks = [];
+    for (const entry of value) {
+        const operatorCode = stringProp(entry, 'operator-code');
+        if (operatorCode === undefined) {
+            continue;
+        }
+        const name = stringProp(entry, 'operator-long') ?? stringProp(entry, 'operator-short');
+        const availability = AVAILABILITY[numberProp(entry, 'status') ?? 0] ?? 'unknown';
+        networks.push({
+            operatorCode,
+            ...(name !== undefined ? { operatorName: name } : {}),
+            availability,
+        });
+    }
+    return networks;
+}

package/dist/backend/mm-mutations/sim.d.ts

@@ -0,0 +1,5 @@
+import type { ModemRef, Receipt, SimPukUnlockResult, SimUnlockResult } from '../../ports/index.js';
+import type { MmMutationContext } from './context.js';
+export declare function setPrimarySimSlot(context: MmMutationContext, modem: ModemRef, slotIndex: number): Promise<Receipt>;
+export declare function unlockWithPin(context: MmMutationContext, modem: ModemRef, pin: string): Promise<SimUnlockResult>;
+export declare function unlockWithPuk(context: MmMutationContext, modem: ModemRef, puk: string, newPin: string): Promise<SimPukUnlockResult>;

package/dist/backend/mm-mutations/sim.js

@@ -0,0 +1,49 @@
+import { receipt } from '../../ports/index.js';
+import { MODEM_IFACE } from '../constants.js';
+import { fetchManagedObjects, findInterface, propValue } from '../managed-objects.js';
+import { sendSimPin, sendSimPuk } from '../sim-unlock.js';
+import { describeMutationError } from './context.js';
+export async function setPrimarySimSlot(context, modem, slotIndex) {
+    const slots = await readSlotCount(context, modem);
+    if (slots === undefined) {
+        return receipt('simSlot', 'failed', 'could not read the modem SIM-slot list');
+    }
+    if (slots <= 1) {
+        return receipt('simSlot', 'unsupported', 'single-slot modem has no primary slot to select');
+    }
+    if (slotIndex < 1 || slotIndex > slots) {
+        return receipt('simSlot', 'failed', `slot ${slotIndex} is out of range (1..${slots})`);
+    }
+    return context.actor.runQuiesced({ stableKey: context.resolveStableKey(modem) }, async () => {
+        try {
+            await context.transport.callMethod({
+                destination: context.destination,
+                path: modem,
+                interface: MODEM_IFACE,
+                member: 'SetPrimarySimSlot',
+                signature: 'u',
+                args: [slotIndex],
+            });
+            return receipt('simSlot', 'applied', `primary SIM slot set to ${slotIndex}`);
+        }
+        catch (error) {
+            return receipt('simSlot', 'failed', `SetPrimarySimSlot failed: ${describeMutationError(error)}`);
+        }
+    });
+}
+export function unlockWithPin(context, modem, pin) {
+    return context.actor.run(context.resolveStableKey(modem), () => sendSimPin(context.transport, context.destination, modem, pin));
+}
+export function unlockWithPuk(context, modem, puk, newPin) {
+    return context.actor.run(context.resolveStableKey(modem), () => sendSimPuk(context.transport, context.destination, modem, puk, newPin));
+}
+async function readSlotCount(context, modem) {
+    try {
+        const tree = await fetchManagedObjects(context.transport, context.destination);
+        const slots = propValue(findInterface(tree, modem, MODEM_IFACE), 'SimSlots');
+        return Array.isArray(slots) ? slots.length : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/backend/mm-mutations.d.ts

@@ -6,30 +6,14 @@ export interface MmMutationsDeps {
     readonly transport: DbusTransport;
     readonly actor: ModemActor;
     readonly destination?: string;
-    /** Map a live modem path to its stable actor key (survives replug). */
     readonly resolveStableKey: (modem: ModemRef) => string;
     readonly scanTimeoutMs?: number;
     readonly now?: () => number;
 }
-/** The disruptive + SIM mutations of `ModemManagerPort`, serialized per modem. */
 export declare class MmMutations {
     #private;
     constructor(deps: MmMutationsDeps);
     setRadioModes(modem: ModemRef, preference: DesiredRadio): Promise<Receipt>;
-    /**
-     * `SetCurrentModes` over the RAW `(uu)` masks the modem itself advertised.
-     *
-     * `setRadioModes` above speaks the reconciler's vocabulary — an ordered RAT
-     * preference — and structurally cannot express `MM_MODEM_MODE_NONE`: its preferred
-     * mask is derived from `preferenceOrdered[0]`, so "allow this set and prefer
-     * nothing within it" has no spelling. That is the combination the bench FM350-GL
-     * actually advertises, so a caller selecting an advertised combination verbatim
-     * needs this entry point. It quiesces for the same reason `setRadioModes` does: a
-     * mode change re-registers the radio and drops the bearer underneath NM.
-     *
-     * An `allowed` mask of 0 is refused — that is not a selection, it is a radio with
-     * nothing switched on — while a `preferred` mask of 0 is passed through untouched.
-     */
     setModeCombination(modem: ModemRef, allowed: number, preferred: number): Promise<Receipt>;
     readBands(modem: ModemRef): Promise<BandReadResult>;
     setCurrentBands(modem: ModemRef, bands: readonly string[]): Promise<Receipt>;