@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/backend/mm-location.js

@@ -0,0 +1,237 @@
+// The `Modem.Location` adapter — GNSS status, enable/disable, and the current fix.
+//
+// Three decisions here are load-bearing and easy to undo by accident:
+//
+//   1. `Setup`'s `signal_location` argument is ALWAYS false. Passing true makes MM
+//      broadcast the `Location` property over `PropertiesChanged`, which would put
+//      the operator's coordinates on the system bus for every listener — including
+//      this package's own observer, whose snapshots are logged. The fix is fetched
+//      by an explicit `GetLocation` call instead, so a coordinate only ever exists
+//      where someone asked for it.
+//   2. GNSS runs through `actor.run`, NOT `actor.runQuiesced`. Quiescing exists to
+//      stop NetworkManager racing a disruptive change, and it costs a bearer
+//      deactivation — on a bonded device, dropping a link to switch a GPS receiver
+//      on would be an absurd trade. `Modem.Location.Setup` touches no bearer, so
+//      serialization per modem is all that is needed.
+//   3. Disable CLEARS only the GNSS bits. `3gpp-lac-ci` is the cell-info module's
+//      source; blanking the whole mask would silently switch off a neighbouring
+//      feature the operator never touched.
+import { epochMillis } from '../domain/index.js';
+import { parseNmeaFix } from '../location/nmea.js';
+import { hasGnssSource } from '../ports/index.js';
+import { MM_BUS_NAME, MODEM_LOCATION_IFACE } from './constants.js';
+import { fetchManagedObjects, findInterface, propValue, } from './managed-objects.js';
+/** MMModemLocationSource bits, by decoded source name. */
+const SOURCE_BIT = {
+    '3gpp-lac-ci': 1 << 0,
+    'gps-raw': 1 << 1,
+    'gps-nmea': 1 << 2,
+    'cdma-bs': 1 << 3,
+    'gps-unmanaged': 1 << 4,
+    'agps-msa': 1 << 5,
+    'agps-msb': 1 << 6,
+};
+const GPS_RAW_BIT = SOURCE_BIT['gps-raw'];
+const GPS_NMEA_BIT = SOURCE_BIT['gps-nmea'];
+const GNSS_MASK = GPS_RAW_BIT |
+    GPS_NMEA_BIT |
+    SOURCE_BIT['gps-unmanaged'] |
+    SOURCE_BIT['agps-msa'] |
+    SOURCE_BIT['agps-msb'];
+/** Decode an MMModemLocationSource bitmask into source names. */
+export function decodeLocationSources(mask) {
+    const sources = new Set();
+    for (const [name, bit] of Object.entries(SOURCE_BIT)) {
+        if ((mask & bit) !== 0) {
+            sources.add(name);
+        }
+    }
+    return sources;
+}
+export function encodeLocationSources(sources) {
+    let mask = 0;
+    for (const source of sources) {
+        mask |= SOURCE_BIT[source] ?? 0;
+    }
+    return mask;
+}
+export class MmLocation {
+    #transport;
+    #actor;
+    #destination;
+    #resolveStableKey;
+    #now;
+    constructor(deps) {
+        this.#transport = deps.transport;
+        this.#actor = deps.actor;
+        this.#destination = deps.destination ?? MM_BUS_NAME;
+        this.#resolveStableKey = deps.resolveStableKey;
+        this.#now = deps.now ?? Date.now;
+    }
+    async getLocationStatus(modem) {
+        const props = await this.#readLocationProps(modem);
+        if (props === undefined) {
+            return { ok: false, reason: 'the modem does not expose a Location interface' };
+        }
+        return { ok: true, status: statusOf(props) };
+    }
+    enableGnss(modem, sources) {
+        return this.#actor.run(this.#resolveStableKey(modem), async () => {
+            const props = await this.#readLocationProps(modem);
+            if (props === undefined) {
+                return refused('the modem does not expose a Location interface');
+            }
+            const status = statusOf(props);
+            if (!status.gnssCapable) {
+                return refused('the modem advertises no GNSS source', status.enabledSources);
+            }
+            const requested = encodeLocationSources(sources) & maskOfNames(status.capabilities);
+            if (requested === 0) {
+                return refused('none of the requested GNSS sources is advertised by this modem', status.enabledSources);
+            }
+            const target = maskOfNames(status.enabledSources) | requested;
+            return this.#setup(modem, target, 'GNSS enabled');
+        });
+    }
+    disableGnss(modem) {
+        return this.#actor.run(this.#resolveStableKey(modem), async () => {
+            const props = await this.#readLocationProps(modem);
+            if (props === undefined) {
+                return refused('the modem does not expose a Location interface');
+            }
+            const status = statusOf(props);
+            const target = maskOfNames(status.enabledSources) & ~GNSS_MASK;
+            return this.#setup(modem, target, 'GNSS disabled');
+        });
+    }
+    async readFix(modem) {
+        const props = await this.#readLocationProps(modem);
+        if (props === undefined) {
+            return { outcome: 'unsupported', reason: 'the modem does not expose a Location interface' };
+        }
+        const status = statusOf(props);
+        if (!status.gnssCapable) {
+            return { outcome: 'unsupported', reason: 'the modem advertises no GNSS source' };
+        }
+        if (!status.gnssEnabled) {
+            return { outcome: 'disabled', reason: 'GNSS is switched off on this modem' };
+        }
+        let reply;
+        try {
+            reply = await this.#transport.callMethod({
+                destination: this.#destination,
+                path: modem,
+                interface: MODEM_LOCATION_IFACE,
+                member: 'GetLocation',
+            });
+        }
+        catch (error) {
+            return { outcome: 'error', reason: `GetLocation failed: ${describe(error)}` };
+        }
+        const fix = decodeFix(reply.body[0], epochMillis(this.#now()));
+        return fix === undefined
+            ? { outcome: 'no-fix', reason: 'the receiver has not acquired a position' }
+            : { outcome: 'fix', fix };
+    }
+    async #setup(modem, mask, appliedReason) {
+        try {
+            await this.#transport.callMethod({
+                destination: this.#destination,
+                path: modem,
+                interface: MODEM_LOCATION_IFACE,
+                member: 'Setup',
+                signature: 'ub',
+                args: [mask, false],
+            });
+        }
+        catch (error) {
+            return {
+                outcome: 'failed',
+                reason: `Location.Setup failed: ${describe(error)}`,
+                enabledSources: new Set(),
+            };
+        }
+        return {
+            outcome: 'applied',
+            reason: appliedReason,
+            enabledSources: decodeLocationSources(mask),
+        };
+    }
+    async #readLocationProps(modem) {
+        try {
+            const tree = await fetchManagedObjects(this.#transport, this.#destination);
+            return findInterface(tree, modem, MODEM_LOCATION_IFACE);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+function maskOfNames(names) {
+    return encodeLocationSources(names);
+}
+function refused(reason, enabled = new Set()) {
+    return { outcome: 'unsupported', reason, enabledSources: enabled };
+}
+function statusOf(props) {
+    const capabilities = decodeLocationSources(maskProp(props, 'Capabilities'));
+    const enabledSources = decodeLocationSources(maskProp(props, 'Enabled'));
+    return {
+        capabilities,
+        enabledSources,
+        gnssCapable: hasGnssSource(capabilities),
+        gnssEnabled: hasGnssSource(enabledSources),
+    };
+}
+function maskProp(props, name) {
+    const value = propValue(props, name);
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function entryValue(payload, bit) {
+    if (!Array.isArray(payload)) {
+        return undefined;
+    }
+    for (const entry of payload) {
+        if (Number(entry[0]) === bit) {
+            return entry[1]?.value;
+        }
+    }
+    return undefined;
+}
+function numberField(props, name) {
+    const value = propValue(props, name);
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Prefer MM's pre-decoded `gps-raw` dict; fall back to parsing the `gps-nmea`
+ * sentences. A raw entry that is present but carries no usable coordinate pair is
+ * NOT treated as a fix — MM populates the key as soon as the source is on.
+ */
+function decodeFix(payload, observedAt) {
+    const raw = entryValue(payload, GPS_RAW_BIT);
+    if (Array.isArray(raw)) {
+        const props = raw;
+        const latitude = numberField(props, 'latitude');
+        const longitude = numberField(props, 'longitude');
+        if (latitude !== undefined && longitude !== undefined) {
+            const altitude = numberField(props, 'altitude');
+            const utcTime = propValue(props, 'utc-time');
+            return {
+                latitude,
+                longitude,
+                ...(altitude === undefined ? {} : { altitude }),
+                ...(typeof utcTime === 'string' ? { utcTime } : {}),
+                observedAt,
+            };
+        }
+    }
+    const nmea = entryValue(payload, GPS_NMEA_BIT);
+    if (typeof nmea !== 'string') {
+        return undefined;
+    }
+    const parsed = parseNmeaFix(nmea);
+    return parsed === undefined ? undefined : { ...parsed, observedAt };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,42 @@
+import type { DesiredRadio } from '../domain/index.js';
+import type { BandReadResult, InhibitLease, ModemRef, NetworkScanResult, Receipt, SimPukUnlockResult, SimUnlockResult } from '../ports/index.js';
+import type { DbusTransport } from '../transport/index.js';
+import type { ModemActor } from './modem-actor.js';
+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>;
+    setPrimarySimSlot(modem: ModemRef, slotIndex: number): Promise<Receipt>;
+    sendPin(modem: ModemRef, pin: string): Promise<SimUnlockResult>;
+    sendPuk(modem: ModemRef, puk: string, newPin: string): Promise<SimPukUnlockResult>;
+    scanNetworks(modem: ModemRef): Promise<NetworkScanResult>;
+    inhibit(uid: string): Promise<InhibitLease>;
+    uninhibit(lease: InhibitLease): Promise<void>;
+}

package/dist/backend/mm-mutations.js

@@ -0,0 +1,259 @@
+// The ModemManager mutations — the disruptive-and-SIM half of `ModemManagerPort`.
+//
+// Every disruptive op runs through the shared per-modem `ModemActor` (serialized on
+// the STABLE key, so two ops on one modem never interleave and a replug keeps the
+// same queue). Mode and slot changes additionally run QUIESCED (NM briefly stands
+// down first, via the actor's quiesce hook). PIN / PUK / scan serialize too but do
+// NOT quiesce — they don't touch the bearer. NONE of these methods can reach a bearer
+// or connect verb: the port has none, and the fake's tripwire proves it at test time.
+import { decodeBandList, encodeBandList, isResetSelection } from '../band/index.js';
+import { epochMillis } from '../domain/index.js';
+import { receipt } from '../ports/index.js';
+import { MM_BUS_NAME, MM_MANAGER_IFACE, MM_ROOT_PATH, MODEM_IFACE, MODEM3GPP_IFACE, } from './constants.js';
+import { fetchManagedObjects, findInterface, numberProp, propValue, stringProp, } from './managed-objects.js';
+import { sendSimPin, sendSimPuk } from './sim-unlock.js';
+/** MMModemMode bit per RAT family (2G/3G/4G/5G). */
+const MODE_BIT = { gsm: 2, umts: 4, lte: 8, '5gnr': 16 };
+/** MMModem3gppNetworkAvailability → the port's availability. */
+const AVAILABILITY = {
+    0: 'unknown',
+    1: 'available',
+    2: 'current',
+    3: 'forbidden',
+};
+/** A network scan can take a long time — MM's own default is not enough. */
+const DEFAULT_SCAN_TIMEOUT_MS = 300_000;
+/** The disruptive + SIM mutations of `ModemManagerPort`, serialized per modem. */
+export class MmMutations {
+    #transport;
+    #actor;
+    #destination;
+    #resolveStableKey;
+    #scanTimeoutMs;
+    #now;
+    constructor(deps) {
+        this.#transport = deps.transport;
+        this.#actor = deps.actor;
+        this.#destination = deps.destination ?? MM_BUS_NAME;
+        this.#resolveStableKey = deps.resolveStableKey;
+        this.#scanTimeoutMs = deps.scanTimeoutMs ?? DEFAULT_SCAN_TIMEOUT_MS;
+        this.#now = deps.now ?? Date.now;
+    }
+    setRadioModes(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 this.#actor.runQuiesced({ stableKey: this.#resolveStableKey(modem) }, async () => {
+            try {
+                await this.#transport.callMethod({
+                    destination: this.#destination,
+                    path: modem,
+                    interface: MODEM_IFACE,
+                    member: 'SetCurrentModes',
+                    signature: '(uu)',
+                    args: [[allowed, preferredMask]],
+                });
+                return receipt('radio', 'applied', 'radio mode preference applied');
+            }
+            catch (error) {
+                return receipt('radio', 'failed', `SetCurrentModes failed: ${describe(error)}`);
+            }
+        });
+    }
+    /**
+     * `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, allowed, preferred) {
+        if (allowed === 0) {
+            return Promise.resolve(receipt('radio', 'failed', 'no radio modes were requested'));
+        }
+        return this.#actor.runQuiesced({ stableKey: this.#resolveStableKey(modem) }, async () => {
+            try {
+                await this.#transport.callMethod({
+                    destination: this.#destination,
+                    path: modem,
+                    interface: MODEM_IFACE,
+                    member: 'SetCurrentModes',
+                    signature: '(uu)',
+                    args: [[allowed, preferred]],
+                });
+                return receipt('radio', 'applied', 'radio mode combination applied');
+            }
+            catch (error) {
+                return receipt('radio', 'failed', `SetCurrentModes failed: ${describe(error)}`);
+            }
+        });
+    }
+    async readBands(modem) {
+        try {
+            const tree = await fetchManagedObjects(this.#transport, this.#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: ${describe(error)}` };
+        }
+    }
+    // Quiesced like `setRadioModes`, and for the same reason: a band change
+    // re-registers the radio, so NM must stand down before the bearer drops
+    // underneath it rather than after.
+    setCurrentBands(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}"`));
+        }
+        const values = encoded.values;
+        return this.#actor.runQuiesced({ stableKey: this.#resolveStableKey(modem) }, async () => {
+            try {
+                await this.#transport.callMethod({
+                    destination: this.#destination,
+                    path: modem,
+                    interface: MODEM_IFACE,
+                    member: 'SetCurrentBands',
+                    signature: 'au',
+                    args: [values],
+                });
+                return receipt('band', 'applied', isResetSelection(bands) ? 'band lock released' : `bands set to ${bands.join(', ')}`);
+            }
+            catch (error) {
+                return receipt('band', 'failed', `SetCurrentBands failed: ${describe(error)}`);
+            }
+        });
+    }
+    async setPrimarySimSlot(modem, slotIndex) {
+        const slots = await this.#readSlotCount(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 this.#actor.runQuiesced({ stableKey: this.#resolveStableKey(modem) }, async () => {
+            try {
+                await this.#transport.callMethod({
+                    destination: this.#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: ${describe(error)}`);
+            }
+        });
+    }
+    sendPin(modem, pin) {
+        return this.#actor.run(this.#resolveStableKey(modem), () => sendSimPin(this.#transport, this.#destination, modem, pin));
+    }
+    sendPuk(modem, puk, newPin) {
+        return this.#actor.run(this.#resolveStableKey(modem), () => sendSimPuk(this.#transport, this.#destination, modem, puk, newPin));
+    }
+    scanNetworks(modem) {
+        return this.#actor.run(this.#resolveStableKey(modem), async () => {
+            try {
+                const reply = await this.#transport.callMethod({
+                    destination: this.#destination,
+                    path: modem,
+                    interface: MODEM3GPP_IFACE,
+                    member: 'Scan',
+                    timeoutMs: this.#scanTimeoutMs,
+                });
+                return { ok: true, networks: parseScan(reply.body[0]) };
+            }
+            catch (error) {
+                return { ok: false, reason: `network scan failed: ${describe(error)}` };
+            }
+        });
+    }
+    async inhibit(uid) {
+        await this.#inhibitDevice(uid, true);
+        return { uid, acquiredAt: epochMillis(this.#now()) };
+    }
+    async uninhibit(lease) {
+        await this.#inhibitDevice(lease.uid, false);
+    }
+    #inhibitDevice(uid, inhibit) {
+        return this.#transport.callMethod({
+            destination: this.#destination,
+            path: MM_ROOT_PATH,
+            interface: MM_MANAGER_IFACE,
+            member: 'InhibitDevice',
+            signature: 'sb',
+            args: [uid, inhibit],
+        });
+    }
+    async #readSlotCount(modem) {
+        try {
+            const tree = await fetchManagedObjects(this.#transport, this.#destination);
+            const slots = propValue(findInterface(tree, modem, MODEM_IFACE), 'SimSlots');
+            return Array.isArray(slots) ? slots.length : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** OR of the MMModemMode bits for a set of RATs. */
+function maskOf(rats) {
+    let mask = 0;
+    for (const rat of rats) {
+        mask |= MODE_BIT[rat];
+    }
+    return mask;
+}
+/** Parse a `Modem3gpp.Scan` reply (`aa{sv}` → dicts) into scanned networks. */
+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;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/backend/modem-actor.d.ts

@@ -0,0 +1,41 @@
+import type { ConnectionId, DeviceIfname } from '../ports/index.js';
+/** What a quiesce lease is taken over — the modem, and (once A4.1 knows them) its
+ *  NM connection + device. In A3.3 only `stableKey` is populated. */
+export interface QuiesceTarget {
+    readonly stableKey: string;
+    readonly connectionId?: ConnectionId;
+    readonly deviceIfname?: DeviceIfname;
+}
+/** A held quiesce lease — released (reactivating the connection) when the op ends. */
+export interface QuiesceLeaseHandle {
+    release(): Promise<void>;
+}
+/**
+ * The NM-quiesce coordination hook the actor calls around a disruptive mode/slot
+ * change. A4.1 wires the real `nmcli` lease (verify-active → `device disconnect` →
+ * hold → reactivate); A3.3 ships `NO_OP_QUIESCE`, whose call site + shape are the
+ * exact seam A4.1 fills in.
+ */
+export interface QuiesceHook {
+    acquire(target: QuiesceTarget): Promise<QuiesceLeaseHandle>;
+}
+/** The A3.3 default quiesce hook — acquires nothing, releases nothing. */
+export declare const NO_OP_QUIESCE: QuiesceHook;
+/**
+ * A per-modem serialized actor. `run` serializes a task behind every prior task for
+ * the same stable key; `runQuiesced` additionally holds an NM quiesce lease for the
+ * task's duration. Different stable keys never block one another.
+ */
+export declare class ModemActor {
+    #private;
+    constructor(quiesce?: QuiesceHook);
+    /** Run `task` serialized behind every prior task for `stableKey`. */
+    run<T>(stableKey: string, task: () => Promise<T>): Promise<T>;
+    /**
+     * Run `task` serialized for `target.stableKey` with an NM quiesce lease held for
+     * its whole duration — the lease is always released, even if `task` throws.
+     */
+    runQuiesced<T>(target: QuiesceTarget, task: () => Promise<T>): Promise<T>;
+    /** Number of modems with a live queue — exposed for leak / idle assertions. */
+    get activeKeyCount(): number;
+}

package/dist/backend/modem-actor.js

@@ -0,0 +1,78 @@
+// The shared per-modem disruptive-operation actor.
+//
+// EVERY disruptive modem operation funnels through ONE serialization queue PER
+// MODEM: radio-mode changes and primary-slot changes (A3.3), the recovery ladder
+// (A3.4), and USB-mode / AT transitions (A4.2) all route through the SAME actor so
+// two disruptive ops on ONE modem can never interleave. Ops on DIFFERENT modems run
+// independently — each modem owns its own queue.
+//
+// The queue is keyed on the STABLE identity key (A3.2's `stableKey`), NOT the
+// transient D-Bus object path. A modem that unplugs and replugs into the same slot
+// resolves to the same stable key, so serialization survives the replug (the path
+// changed, the queue did not).
+//
+// Mode and slot changes additionally coordinate with NetworkManager through the
+// `QuiesceHook` — before a disruptive change NM briefly deactivates the connection so
+// it cannot race MM's own re-activation, then reactivates it on release. In A3.3 the
+// hook is a NO-OP stub with the exact lease shape A4.1's real nmcli adapter will fill
+// in (`NetworkManagerPort.acquireQuiesceLease`).
+const NO_OP_LEASE = {
+    release() {
+        return Promise.resolve();
+    },
+};
+/** The A3.3 default quiesce hook — acquires nothing, releases nothing. */
+export const NO_OP_QUIESCE = {
+    acquire() {
+        return Promise.resolve(NO_OP_LEASE);
+    },
+};
+/**
+ * A per-modem serialized actor. `run` serializes a task behind every prior task for
+ * the same stable key; `runQuiesced` additionally holds an NM quiesce lease for the
+ * task's duration. Different stable keys never block one another.
+ */
+export class ModemActor {
+    #quiesce;
+    // Tail of each modem's queue — a promise that settles when the last-enqueued task
+    // for that key finishes (errors swallowed so the chain never breaks).
+    #tails = new Map();
+    constructor(quiesce = NO_OP_QUIESCE) {
+        this.#quiesce = quiesce;
+    }
+    /** Run `task` serialized behind every prior task for `stableKey`. */
+    run(stableKey, task) {
+        const prior = this.#tails.get(stableKey) ?? Promise.resolve();
+        // `then(task, task)` runs `task` whether the prior task resolved OR rejected,
+        // so one failure never stalls the queue.
+        const result = prior.then(task, task);
+        const settled = result.then(() => undefined, () => undefined);
+        this.#tails.set(stableKey, settled);
+        // Drop the entry once this task was the last one, to bound the map.
+        void settled.then(() => {
+            if (this.#tails.get(stableKey) === settled) {
+                this.#tails.delete(stableKey);
+            }
+        });
+        return result;
+    }
+    /**
+     * Run `task` serialized for `target.stableKey` with an NM quiesce lease held for
+     * its whole duration — the lease is always released, even if `task` throws.
+     */
+    runQuiesced(target, task) {
+        return this.run(target.stableKey, async () => {
+            const lease = await this.#quiesce.acquire(target);
+            try {
+                return await task();
+            }
+            finally {
+                await lease.release();
+            }
+        });
+    }
+    /** Number of modems with a live queue — exposed for leak / idle assertions. */
+    get activeKeyCount() {
+        return this.#tails.size;
+    }
+}