@ceralive/modem-control 0.2.0 → 1.1.0

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

package/dist/backend/nm-auto-apn.d.ts

@@ -0,0 +1,54 @@
+import { type Receipt } from '../ports/index.js';
+import { type NmcliResult, type NmcliRunner } from './nmcli-runner.js';
+/** The single advisory Auto-APN raises when it cannot be honored. */
+export declare const AUTO_APN_ADVISORY = "autoApnUnavailable";
+export type AutoApnAdvisory = typeof AUTO_APN_ADVISORY;
+/** The outcome of an Auto-APN transition: a receipt plus an optional advisory flag. */
+export interface AutoApnTransitionResult {
+    readonly receipt: Receipt;
+    readonly advisory?: AutoApnAdvisory;
+}
+/** Explicit APN + credentials for the manual direction of a transition. */
+export interface ManualApn {
+    readonly apn: string;
+    readonly username?: string;
+    readonly password?: string;
+}
+/** Parse `nmcli tool, version 1.42.4` → `{ major, minor }` (null on garbage). */
+export declare function parseNmVersion(output: string): {
+    major: number;
+    minor: number;
+} | null;
+/** `true` iff the parsed NM version is >= 1.22 (auto-config support floor). */
+export declare function autoApnSupportedByVersion(version: {
+    major: number;
+    minor: number;
+}): boolean;
+/**
+ * Decide from a `nmcli --version` result whether Auto-APN is available on this install.
+ * Fail-CLOSED — an unreadable/garbled version is "not capable", so we never claim
+ * Auto-APN works when we cannot prove it does.
+ */
+export declare function autoApnCapableFromVersion(result: NmcliResult): boolean;
+/** Boot capability probe: run `nmcli --version` and resolve Auto-APN availability. */
+export declare function probeAutoApnCapability(runner: NmcliRunner): Promise<boolean>;
+/**
+ * ONE atomic `connection modify` that flips a profile to Auto-APN: clears every
+ * credential AND sets `gsm.auto-config yes` in the SAME invocation. Order/atomicity
+ * matter — NM rejects `auto-config yes` while any credential is still set, so the clear
+ * and the enable MUST land together (never two modifies).
+ */
+export declare function toAutoArgs(id: string): string[];
+/**
+ * The exact reverse: ONE atomic `connection modify` restoring explicit APN + creds and
+ * clearing `gsm.auto-config`, with password-flags matching the (new) password.
+ */
+export declare function toManualArgs(id: string, creds: ManualApn): string[];
+/**
+ * Classify a `connection up` result into a receipt (+ advisory). `underAuto` marks that
+ * the profile being activated is an Auto-APN profile, so an APN failure is the "no MBPI
+ * match for this SIM" case → unsupported + advisory rather than a hard fail.
+ */
+export declare function classifyActivation(result: NmcliResult, options: {
+    readonly underAuto: boolean;
+}): AutoApnTransitionResult;

package/dist/backend/nm-auto-apn.js

@@ -0,0 +1,124 @@
+// Auto-APN: boot capability probe, the two atomic transition argv builders, and the
+// activation-result classifier.
+//
+// Auto-APN (`apn:"auto"` ⇒ NM `gsm.auto-config yes`) needs NetworkManager >= 1.22
+// (bookworm ships 1.42). A boot capability probe reads nmcli's version — replacing any
+// implicit/hardcoded gating — and when NM is too old an auto policy resolves to
+// `unsupported` up front with the `autoApnUnavailable` advisory (no modify at all).
+//
+// When NM DOES support auto-config a bad/unknown SIM can still have no MBPI match: the
+// connection fails to activate with a GSM_APN_FAILED device-state reason. That is
+// classified at ACTIVATION, not guessed ahead of time — reactivate the exact
+// (uuid, ifname) pair, await the terminal state, then:
+//   GSM_APN_FAILED under an auto profile → unsupported + autoApnUnavailable advisory
+//   any other activation error            → failed
+//   nmcli's own activation wait timed out → pending
+import { receipt } from '../ports/index.js';
+import { cliArg, passwordFlags } from './nm-gsm-fields.js';
+import { runNmcli } from './nmcli-runner.js';
+/** The single advisory Auto-APN raises when it cannot be honored. */
+export const AUTO_APN_ADVISORY = 'autoApnUnavailable';
+const AUTO_CONFIG_MIN_MAJOR = 1;
+const AUTO_CONFIG_MIN_MINOR = 22;
+/** nmcli's own `--wait` timeout exit status (nmcli(1): 3 = timeout expired). */
+const NMCLI_EXIT_TIMEOUT = 3;
+const APN_FAILED = /gsm[_-]?apn[_-]?failed/i;
+/** Parse `nmcli tool, version 1.42.4` → `{ major, minor }` (null on garbage). */
+export function parseNmVersion(output) {
+    const match = /version\s+(\d+)\.(\d+)/i.exec(output);
+    if (match?.[1] === undefined || match[2] === undefined) {
+        return null;
+    }
+    return { major: Number(match[1]), minor: Number(match[2]) };
+}
+/** `true` iff the parsed NM version is >= 1.22 (auto-config support floor). */
+export function autoApnSupportedByVersion(version) {
+    if (version.major !== AUTO_CONFIG_MIN_MAJOR) {
+        return version.major > AUTO_CONFIG_MIN_MAJOR;
+    }
+    return version.minor >= AUTO_CONFIG_MIN_MINOR;
+}
+/**
+ * Decide from a `nmcli --version` result whether Auto-APN is available on this install.
+ * Fail-CLOSED — an unreadable/garbled version is "not capable", so we never claim
+ * Auto-APN works when we cannot prove it does.
+ */
+export function autoApnCapableFromVersion(result) {
+    if (result.exitCode !== 0) {
+        return false;
+    }
+    const version = parseNmVersion(result.stdout);
+    return version !== null && autoApnSupportedByVersion(version);
+}
+/** Boot capability probe: run `nmcli --version` and resolve Auto-APN availability. */
+export async function probeAutoApnCapability(runner) {
+    return autoApnCapableFromVersion(await runNmcli(runner, ['--version']));
+}
+/**
+ * ONE atomic `connection modify` that flips a profile to Auto-APN: clears every
+ * credential AND sets `gsm.auto-config yes` in the SAME invocation. Order/atomicity
+ * matter — NM rejects `auto-config yes` while any credential is still set, so the clear
+ * and the enable MUST land together (never two modifies).
+ */
+export function toAutoArgs(id) {
+    return [
+        'connection',
+        'modify',
+        id,
+        'gsm.apn',
+        '',
+        'gsm.username',
+        '',
+        'gsm.password',
+        '',
+        'gsm.password-flags',
+        '4',
+        'gsm.auto-config',
+        'yes',
+    ];
+}
+/**
+ * The exact reverse: ONE atomic `connection modify` restoring explicit APN + creds and
+ * clearing `gsm.auto-config`, with password-flags matching the (new) password.
+ */
+export function toManualArgs(id, creds) {
+    return [
+        'connection',
+        'modify',
+        id,
+        'gsm.apn',
+        cliArg(creds.apn),
+        'gsm.username',
+        cliArg(creds.username),
+        'gsm.password',
+        cliArg(creds.password),
+        'gsm.password-flags',
+        passwordFlags(creds.password),
+        'gsm.auto-config',
+        'no',
+    ];
+}
+/**
+ * Classify a `connection up` result into a receipt (+ advisory). `underAuto` marks that
+ * the profile being activated is an Auto-APN profile, so an APN failure is the "no MBPI
+ * match for this SIM" case → unsupported + advisory rather than a hard fail.
+ */
+export function classifyActivation(result, options) {
+    if (result.exitCode === 0) {
+        return { receipt: receipt('connection', 'applied', 'connection activated') };
+    }
+    if (result.exitCode === NMCLI_EXIT_TIMEOUT || /timeout/i.test(result.stderr)) {
+        return {
+            receipt: receipt('connection', 'pending', 'activation wait timed out; terminal state unknown'),
+        };
+    }
+    if (options.underAuto && (APN_FAILED.test(result.stderr) || APN_FAILED.test(result.stdout))) {
+        return {
+            receipt: receipt('connection', 'unsupported', 'Auto-APN found no operator match for this SIM'),
+            advisory: AUTO_APN_ADVISORY,
+        };
+    }
+    return {
+        receipt: receipt('connection', 'failed', result.stderr || 'connection activation failed'),
+    };
+}

package/dist/backend/nm-gsm-fields.d.ts

@@ -0,0 +1,23 @@
+import type { ConnectionId, GsmProfile, GsmProfileInput, GsmProfilePatch } from '../ports/index.js';
+export declare const cliArg: (value: string | undefined) => string;
+/** NM secret-flags: no password ⇒ NOT_REQUIRED ("4"); password set ⇒ NONE ("0"). */
+export declare const passwordFlags: (password: string | undefined) => string;
+/**
+ * The nine `gsm.*` + `connection.*` key/value pairs for a profile, in stable order.
+ * With `autoConfig` set the creds are forced empty (NM rejects `auto-config yes` while
+ * any credential is present — nm-setting-gsm.c:440-447), so an Auto-APN create is always
+ * NM-valid by construction.
+ */
+export declare function gsmFieldPairs(input: GsmProfileInput): Array<[string, string]>;
+/** Flatten key/value pairs into the alternating argv nmcli expects. */
+export declare function flattenPairs(pairs: ReadonlyArray<readonly [string, string]>): string[];
+/** `connection add type gsm con-name <name> <nine fields>` — device-exact create argv. */
+export declare function createGsmArgs(input: GsmProfileInput): string[];
+/**
+ * The key/value pairs for a `connection modify`. Roaming (home-only) and the manual
+ * operator id move together — turning roaming off clears `gsm.network-id`, honoring the
+ * `gsm.network-id = roaming ? id : ""` invariant in the SAME modify.
+ */
+export declare function patchPairs(patch: GsmProfilePatch): string[];
+/** Map an nmcli terse readback back onto a `GsmProfile` (inverse of the write parity). */
+export declare function buildProfile(id: ConnectionId, settings: Map<string, string>): GsmProfile;