@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/backend/mapping.js

@@ -0,0 +1,148 @@
+// Pure mapping: a decoded ModemManager object tree → a `CellularSnapshot`.
+//
+// A3.1 is lifecycle-only. This mapper is DELIBERATELY conservative: it captures
+// identity, presence, source health, radio power, and MM state — the facts the
+// observer needs to order and reconcile modems — but leaves the richer 3GPP
+// registration + access-technology set as `unknown`/empty. Faithful registration and
+// cell-info normalisation are A3.2 (identity ladder) and A3.3 (Signal.Setup / cell
+// info); mapping them here would either be a guess or trip the domain guards. The
+// snapshot this produces is always guard-valid by construction.
+import { imeiEquipmentId, subscriberNumber as makeSubscriberNumber, subscriptionId as makeSubscriptionId, runtimePath, } from '../domain/index.js';
+import { MODEM_IFACE, MODEM3GPP_IFACE, SIM_IFACE } from './constants.js';
+import { findInterface, followObjectPath, numberProp, pathsWithInterface, stringArrayProp, stringProp, } from './managed-objects.js';
+/** MMModemState (`Modem.State`, signed) → the domain `MmState`. */
+function mapMmState(state) {
+    switch (state) {
+        case -1:
+            return 'failed';
+        case 1:
+            return 'initializing';
+        case 2:
+            return 'locked';
+        case 3:
+            return 'disabled';
+        case 4:
+            return 'disabling';
+        case 5:
+            return 'enabling';
+        case 6:
+            return 'enabled';
+        case 7:
+            return 'searching';
+        case 8:
+            return 'registered';
+        case 9:
+            return 'disconnecting';
+        case 10:
+            return 'connecting';
+        case 11:
+            return 'connected';
+        default:
+            return 'unknown';
+    }
+}
+/** MMModemPowerState (`Modem.PowerState`) → the domain `RadioPower`. */
+function mapRadioPower(power) {
+    switch (power) {
+        case 1:
+            return 'off';
+        case 2:
+            return 'low';
+        case 3:
+            return 'on';
+        default:
+            return 'unknown';
+    }
+}
+/** Locked / failed modems keep the radio off; every other state we cannot see as
+ *  off (the guards forbid an active MM state with the radio off), so an unknown
+ *  power reading is treated as `on` when the modem is clearly on the air. */
+function reconcilePower(power, state) {
+    const onTheAir = state === 'enabled' ||
+        state === 'searching' ||
+        state === 'registered' ||
+        state === 'connecting' ||
+        state === 'connected' ||
+        state === 'disconnecting';
+    if (onTheAir && (power === 'unknown' || power === 'off')) {
+        return 'on';
+    }
+    return power;
+}
+/** Read a modem's subscription id (ICCID) from its active SIM object, if any. */
+function readSubscriptionId(tree, modemPath) {
+    const modem = findInterface(tree, modemPath, MODEM_IFACE);
+    const sim = followObjectPath(tree, modem, 'Sim', SIM_IFACE);
+    const iccid = stringProp(sim, 'SimIdentifier');
+    return iccid !== undefined && iccid.length > 0 ? makeSubscriptionId(iccid) : undefined;
+}
+/**
+ * The SIM's own number(s) from `Modem.OwnNumbers`, or `undefined` when the
+ * carrier published none. Most SIMs carry no MSISDN at all, so an absent or
+ * empty property is the ordinary case and must read as "not reported" rather
+ * than as an empty list an operator could mistake for a failed read.
+ */
+function readOwnNumbers(modem) {
+    const raw = stringArrayProp(modem, 'OwnNumbers');
+    if (raw === undefined) {
+        return undefined;
+    }
+    const numbers = raw
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0)
+        .map((value) => makeSubscriberNumber(value));
+    return numbers.length > 0 ? numbers : undefined;
+}
+/** Map ONE modem object to its dimensions. The modem must expose `Modem`. */
+export function mapModem(tree, modemPath) {
+    const modem = findInterface(tree, modemPath, MODEM_IFACE);
+    const modem3gpp = findInterface(tree, modemPath, MODEM3GPP_IFACE);
+    const equipment = stringProp(modem, 'EquipmentIdentifier') ?? stringProp(modem3gpp, 'Imei') ?? '';
+    const mmState = mapMmState(numberProp(modem, 'State'));
+    const radioPower = reconcilePower(mapRadioPower(numberProp(modem, 'PowerState')), mmState);
+    const sub = readSubscriptionId(tree, modemPath);
+    const ownNumbers = readOwnNumbers(modem);
+    return {
+        identity: {
+            equipmentId: imeiEquipmentId(equipment),
+            runtimePath: runtimePath(modemPath),
+            ...(sub !== undefined ? { subscriptionId: sub } : {}),
+            ...(ownNumbers !== undefined ? { ownNumbers } : {}),
+        },
+        presence: 'present',
+        sourceHealth: 'live',
+        simSlots: [],
+        radioPower,
+        mmState,
+        // Conservative: 3GPP registration + RAT set are A3.3's job (see file header).
+        registration: { status: 'unknown', activeRats: new Set() },
+        nmActivation: 'unavailable',
+        dataInterface: { present: false },
+        reconcileStatus: 'pending',
+        recoveryState: { stage: 'idle', attempts: 0 },
+    };
+}
+/** Every modem path in the tree (objects exposing the `Modem` interface), in order. */
+export function modemPaths(tree) {
+    return pathsWithInterface(tree, MODEM_IFACE);
+}
+/** A stable fingerprint of a mapped modem's meaningful dimensions (ignores revision
+ *  and source health), used to suppress redundant revision bumps on identical reads. */
+export function fingerprint(mapped) {
+    return JSON.stringify({
+        id: mapped.identity.equipmentId,
+        sub: mapped.identity.subscriptionId ?? null,
+        own: mapped.identity.ownNumbers ?? null,
+        path: mapped.identity.runtimePath,
+        presence: mapped.presence,
+        radioPower: mapped.radioPower,
+        mmState: mapped.mmState,
+        registration: {
+            status: mapped.registration.status,
+            rats: [...mapped.registration.activeRats].sort(),
+        },
+        nmActivation: mapped.nmActivation,
+        dataInterface: mapped.dataInterface,
+        reconcileStatus: mapped.reconcileStatus,
+    });
+}

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

@@ -0,0 +1,44 @@
+import type { DesiredRadio } from '../domain/index.js';
+import type { BandReadResult, InhibitLease, ModemManagerPort, ModemRef, NetworkScanResult, ObservationList, ObservationListener, Receipt, SimPukUnlockResult, SimUnlockResult, Unsubscribe } from '../ports/index.js';
+import type { DbusTransport } from '../transport/index.js';
+import { type CellReading } from './cell-info.js';
+import { type ModemEnrichment } from './enrichment.js';
+import { ModemActor, type QuiesceHook } from './modem-actor.js';
+import { type SignalCadence } from './signal-setup.js';
+export interface MmDbusBackendOptions {
+    readonly transport: DbusTransport;
+    readonly destination?: string;
+    readonly actor?: ModemActor;
+    /** NM quiesce hook for disruptive mode/slot changes (A3.3 default: no-op). */
+    readonly quiesce?: QuiesceHook;
+    /** Signal.Setup reporting interval in seconds. */
+    readonly signalIntervalSeconds?: number;
+    readonly scanTimeoutMs?: number;
+    readonly now?: () => number;
+}
+/** The real D-Bus ModemManager backend: observation + mutations + Signal.Setup. */
+export declare class MmDbusBackend implements ModemManagerPort {
+    #private;
+    constructor(options: MmDbusBackendOptions);
+    start(): Promise<ObservationList>;
+    observe(listener: ObservationListener): Unsubscribe;
+    stop(): Promise<void>;
+    setRadioModes(modem: ModemRef, preference: DesiredRadio): Promise<Receipt>;
+    setModeCombination(modem: ModemRef, allowed: number, preferred: number): Promise<Receipt>;
+    setPrimarySimSlot(modem: ModemRef, slotIndex: number): Promise<Receipt>;
+    readBands(modem: ModemRef): Promise<BandReadResult>;
+    setCurrentBands(modem: ModemRef, bands: readonly string[]): 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>;
+    /** Whether periodic signal reporting is configured for a modem (Signal.Setup). */
+    signalCadence(modem: ModemRef): SignalCadence;
+    /** Read the normalized visible-cell list for a modem via `Modem.GetCellInfo`. */
+    readCellInfo(modem: ModemRef): Promise<readonly CellReading[]>;
+    /** Assemble the full read-only enrichment (revision, eSIM, cadence, cell info). */
+    readEnrichment(modem: ModemRef): Promise<ModemEnrichment>;
+}
+/** Construct the real D-Bus ModemManager backend over an A2.4 transport. */
+export declare function createMmDbusBackend(options: MmDbusBackendOptions): MmDbusBackend;

package/dist/backend/mm-backend.js

@@ -0,0 +1,154 @@
+// MmDbusBackend — the real D-Bus `ModemManagerPort`, composed from the A3 parts.
+//
+// It fulfils the whole port: the read side delegates to A3.1's epoch-scoped observer;
+// the mutations run through `MmMutations` (each serialized on the shared per-modem
+// `ModemActor`, keyed on A3.2's STABLE key so serialization survives replug); the
+// Signal.Setup lifecycle is driven off the observer's `onEpochRefresh` hook; and the
+// read-only enrichment (firmware revision, eSIM, signal cadence, normalized cell info)
+// is assembled on demand. One transport is shared by all of them.
+//
+// The `onEpochRefresh` hook is the single integration seam: on every current-epoch
+// authoritative snapshot it (1) rebuilds the live path → stable-key map (so a mutation
+// keys the actor by the durable identity, not the transient path) and (2) re-drives
+// Signal.Setup for that epoch — applying to new modems, re-applying to survivors after
+// an owner change, and never firing for a superseded epoch.
+import { epochMillis } from '../domain/index.js';
+import { normalizeCellInfo } from './cell-info.js';
+import { MM_BUS_NAME, MODEM_IFACE } from './constants.js';
+import { buildEnrichment } from './enrichment.js';
+import { modemIdentityFactsFromTree, resolveModemIdentities } from './identity-ladder.js';
+import { fetchManagedObjects, pathsWithInterface } from './managed-objects.js';
+import { MmMutations } from './mm-mutations.js';
+import { ModemActor } from './modem-actor.js';
+import { createMmDbusObserver } from './observer.js';
+import { SignalSetupManager } from './signal-setup.js';
+/** The real D-Bus ModemManager backend: observation + mutations + Signal.Setup. */
+export class MmDbusBackend {
+    #transport;
+    #destination;
+    #now;
+    #observer;
+    #mutations;
+    #signalSetup;
+    // Live modem path → durable stable key; rebuilt on every epoch snapshot.
+    #stableKeyByPath = new Map();
+    constructor(options) {
+        this.#transport = options.transport;
+        this.#destination = options.destination ?? MM_BUS_NAME;
+        this.#now = options.now ?? Date.now;
+        const actor = options.actor ?? new ModemActor(options.quiesce);
+        this.#signalSetup = new SignalSetupManager({
+            transport: this.#transport,
+            destination: this.#destination,
+            ...(options.signalIntervalSeconds !== undefined
+                ? { intervalSeconds: options.signalIntervalSeconds }
+                : {}),
+        });
+        this.#observer = createMmDbusObserver({
+            transport: this.#transport,
+            destination: this.#destination,
+            onEpochRefresh: (event) => this.#onEpochRefresh(event),
+        });
+        this.#mutations = new MmMutations({
+            transport: this.#transport,
+            actor,
+            destination: this.#destination,
+            resolveStableKey: (modem) => this.#stableKeyByPath.get(modem) ?? modem,
+            ...(options.scanTimeoutMs !== undefined ? { scanTimeoutMs: options.scanTimeoutMs } : {}),
+            now: this.#now,
+        });
+    }
+    // ── observation (delegated to the A3.1 observer) ────────────────────────────────
+    start() {
+        return this.#observer.start();
+    }
+    observe(listener) {
+        return this.#observer.observe(listener);
+    }
+    stop() {
+        return this.#observer.stop();
+    }
+    // ── mutations (serialized per modem through the shared actor) ────────────────────
+    setRadioModes(modem, preference) {
+        return this.#mutations.setRadioModes(modem, preference);
+    }
+    setModeCombination(modem, allowed, preferred) {
+        return this.#mutations.setModeCombination(modem, allowed, preferred);
+    }
+    setPrimarySimSlot(modem, slotIndex) {
+        return this.#mutations.setPrimarySimSlot(modem, slotIndex);
+    }
+    readBands(modem) {
+        return this.#mutations.readBands(modem);
+    }
+    setCurrentBands(modem, bands) {
+        return this.#mutations.setCurrentBands(modem, bands);
+    }
+    sendPin(modem, pin) {
+        return this.#mutations.sendPin(modem, pin);
+    }
+    sendPuk(modem, puk, newPin) {
+        return this.#mutations.sendPuk(modem, puk, newPin);
+    }
+    scanNetworks(modem) {
+        return this.#mutations.scanNetworks(modem);
+    }
+    inhibit(uid) {
+        return this.#mutations.inhibit(uid);
+    }
+    uninhibit(lease) {
+        return this.#mutations.uninhibit(lease);
+    }
+    // ── enrichment (additive, read-only, never gating) ──────────────────────────────
+    /** Whether periodic signal reporting is configured for a modem (Signal.Setup). */
+    signalCadence(modem) {
+        return this.#signalSetup.cadenceFor(modem);
+    }
+    /** Read the normalized visible-cell list for a modem via `Modem.GetCellInfo`. */
+    async readCellInfo(modem) {
+        const provenance = { source: modem, observedAt: epochMillis(this.#now()) };
+        try {
+            const reply = await this.#transport.callMethod({
+                destination: this.#destination,
+                path: modem,
+                interface: MODEM_IFACE,
+                member: 'GetCellInfo',
+            });
+            const cells = Array.isArray(reply.body[0])
+                ? reply.body[0]
+                : [];
+            return normalizeCellInfo(cells, provenance);
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Assemble the full read-only enrichment (revision, eSIM, cadence, cell info). */
+    async readEnrichment(modem) {
+        const [tree, cellInfo] = await Promise.all([
+            fetchManagedObjects(this.#transport, this.#destination),
+            this.readCellInfo(modem),
+        ]);
+        return buildEnrichment(tree, modem, this.#signalSetup.cadenceFor(modem), cellInfo);
+    }
+    #onEpochRefresh(event) {
+        this.#refreshStableKeys(event);
+        this.#signalSetup.applyForEpoch(event.epoch, event.tree);
+    }
+    #refreshStableKeys(event) {
+        const paths = pathsWithInterface(event.tree, MODEM_IFACE);
+        const facts = paths.map((path) => modemIdentityFactsFromTree(event.tree, path));
+        const resolved = resolveModemIdentities(facts);
+        this.#stableKeyByPath.clear();
+        paths.forEach((path, index) => {
+            const entry = resolved[index];
+            if (entry !== undefined) {
+                this.#stableKeyByPath.set(path, entry.stableKey);
+            }
+        });
+    }
+}
+/** Construct the real D-Bus ModemManager backend over an A2.4 transport. */
+export function createMmDbusBackend(options) {
+    return new MmDbusBackend(options);
+}

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

@@ -0,0 +1,21 @@
+import type { FixRead, GnssSource, LocationStatusResult, LocationToggleResult, ModemLocationPort, ModemRef } from '../ports/index.js';
+import type { DbusTransport } from '../transport/index.js';
+import type { ModemActor } from './modem-actor.js';
+/** Decode an MMModemLocationSource bitmask into source names. */
+export declare function decodeLocationSources(mask: number): ReadonlySet<string>;
+export declare function encodeLocationSources(sources: Iterable<string>): number;
+export interface MmLocationDeps {
+    readonly transport: DbusTransport;
+    readonly actor: ModemActor;
+    readonly destination?: string;
+    readonly resolveStableKey: (modem: ModemRef) => string;
+    readonly now?: () => number;
+}
+export declare class MmLocation implements ModemLocationPort {
+    #private;
+    constructor(deps: MmLocationDeps);
+    getLocationStatus(modem: ModemRef): Promise<LocationStatusResult>;
+    enableGnss(modem: ModemRef, sources: readonly GnssSource[]): Promise<LocationToggleResult>;
+    disableGnss(modem: ModemRef): Promise<LocationToggleResult>;
+    readFix(modem: ModemRef): Promise<FixRead>;
+}

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>;
+}