@ceralive/modem-control 1.0.0 → 1.2.0

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;

package/dist/backend/nm-gsm-fields.js

@@ -0,0 +1,107 @@
+// Pure nmcli GSM-connection argv builders — the FULL nine-field write parity today's
+// CeraUI carried (modem-registration.ts `sanitizeModemConfigForNetworkManager` +
+// `addConnectionForModem`), rebuilt from scratch for the device-exact adapter so the
+// greenfield port loses nothing the wrap-first path wrote.
+//
+// The nine fields and their exact NM conventions (`gsm.*` + `connection.*` setting
+// semantics) are the contract A4.1 must not regress:
+//   gsm.apn / gsm.username / gsm.password  — creds ("" when unset)
+//   gsm.password-flags                     — "4" NOT_REQUIRED (no password),
+//                                            "0" NONE / system-stored (password set)
+//   gsm.home-only                          — "yes" ⇒ roaming DISABLED
+//   gsm.network-id                         — manual operator PLMN, only while roaming
+//   gsm.auto-config                        — "yes" ⇒ Auto-APN (creds MUST be empty)
+//   connection.autoconnect                 — always "yes"
+//   connection.autoconnect-retries         — "2"
+// Empty-string fallback; Bun runtime limitation with empty CLI args: a bare
+// `undefined` reaching `Bun.spawn` argv drops the slot and shifts every following
+// token, so every optional nmcli value is coerced to "" first — the same `value || ""`
+// convention CeraUI documented on gsm.apn / gsm.username / gsm.password.
+export const cliArg = (value) => value || '';
+/** NM secret-flags: no password ⇒ NOT_REQUIRED ("4"); password set ⇒ NONE ("0"). */
+export const passwordFlags = (password) => (password ? '0' : '4');
+/** `gsm.network-id` — the manual operator id, and only while roaming (home-only off). */
+const networkIdField = (input) => input.homeOnly ? '' : cliArg(input.networkId);
+/**
+ * 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 function gsmFieldPairs(input) {
+    const auto = input.autoConfig;
+    return [
+        ['gsm.apn', auto ? '' : cliArg(input.apn)],
+        ['gsm.username', auto ? '' : cliArg(input.username)],
+        ['gsm.password', auto ? '' : cliArg(input.password)],
+        ['gsm.password-flags', passwordFlags(auto ? undefined : input.password)],
+        ['gsm.home-only', input.homeOnly ? 'yes' : 'no'],
+        ['gsm.network-id', networkIdField(input)],
+        ['gsm.auto-config', auto ? 'yes' : 'no'],
+        ['connection.autoconnect', 'yes'],
+        ['connection.autoconnect-retries', '2'],
+    ];
+}
+/** Flatten key/value pairs into the alternating argv nmcli expects. */
+export function flattenPairs(pairs) {
+    return pairs.flat();
+}
+/** `connection add type gsm con-name <name> <nine fields>` — device-exact create argv. */
+export function createGsmArgs(input) {
+    return [
+        'connection',
+        'add',
+        'type',
+        'gsm',
+        'con-name',
+        input.connectionName,
+        ...flattenPairs(gsmFieldPairs(input)),
+    ];
+}
+/**
+ * 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 function patchPairs(patch) {
+    const pairs = [];
+    if (patch.connectionName !== undefined) {
+        pairs.push('connection.id', patch.connectionName);
+    }
+    if (patch.apn !== undefined) {
+        pairs.push('gsm.apn', cliArg(patch.apn));
+    }
+    if (patch.username !== undefined) {
+        pairs.push('gsm.username', cliArg(patch.username));
+    }
+    if (patch.password !== undefined) {
+        pairs.push('gsm.password', cliArg(patch.password), 'gsm.password-flags', passwordFlags(patch.password));
+    }
+    if (patch.autoConfig !== undefined) {
+        pairs.push('gsm.auto-config', patch.autoConfig ? 'yes' : 'no');
+    }
+    if (patch.homeOnly !== undefined) {
+        pairs.push('gsm.home-only', patch.homeOnly ? 'yes' : 'no');
+        pairs.push('gsm.network-id', patch.homeOnly ? '' : cliArg(patch.networkId));
+    }
+    else if (patch.networkId !== undefined) {
+        pairs.push('gsm.network-id', cliArg(patch.networkId));
+    }
+    return pairs;
+}
+/** Map an nmcli terse readback back onto a `GsmProfile` (inverse of the write parity). */
+export function buildProfile(id, settings) {
+    const username = settings.get('gsm.username') ?? '';
+    const password = settings.get('gsm.password') ?? '';
+    const networkId = settings.get('gsm.network-id') ?? '';
+    return {
+        connectionId: id,
+        connectionName: settings.get('connection.id') ?? '',
+        apn: settings.get('gsm.apn') ?? '',
+        homeOnly: settings.get('gsm.home-only') === 'yes',
+        autoConfig: settings.get('gsm.auto-config') === 'yes',
+        ...(username !== '' ? { username } : {}),
+        ...(password !== '' ? { password } : {}),
+        ...(networkId !== '' ? { networkId } : {}),
+    };
+}

package/dist/backend/nmcli-nm-port.d.ts

@@ -0,0 +1,28 @@
+import { type ConnectionId, type DeviceIfname, type GsmProfile, type GsmProfileInput, type GsmProfilePatch, type NetworkManagerPort, type QuiesceLease, type Receipt } from '../ports/index.js';
+import { type AutoApnTransitionResult, type ManualApn } from './nm-auto-apn.js';
+import { type NmcliRunner } from './nmcli-runner.js';
+export interface NmcliNmPortOptions {
+    readonly runner: NmcliRunner;
+    /** Resolved once at boot by the capability probe; default `true`. */
+    readonly autoApnCapable?: boolean;
+    readonly leaseTtlMs?: number;
+    readonly now?: () => number;
+}
+export declare class NmcliNmPort implements NetworkManagerPort {
+    #private;
+    constructor(options: NmcliNmPortOptions);
+    createGsmProfile(profile: GsmProfileInput): Promise<GsmProfile>;
+    readGsmProfile(id: ConnectionId): Promise<GsmProfile | undefined>;
+    updateGsmProfile(id: ConnectionId, patch: GsmProfilePatch): Promise<GsmProfile>;
+    deleteGsmProfile(id: ConnectionId): Promise<void>;
+    activate(id: ConnectionId, ifname: DeviceIfname): Promise<Receipt>;
+    deactivate(id: ConnectionId, ifname: DeviceIfname): Promise<Receipt>;
+    acquireQuiesceLease(id: ConnectionId, ifname: DeviceIfname): Promise<QuiesceLease>;
+    releaseQuiesceLease(lease: QuiesceLease): Promise<void>;
+    /** Reactivate every lease held past the TTL — the abandoned-lease watchdog. */
+    sweepExpiredLeases(now?: number): Promise<void>;
+    /** Flip a profile to Auto-APN via ONE atomic modify, then reactivate + classify. */
+    transitionToAuto(id: ConnectionId, ifname: DeviceIfname): Promise<AutoApnTransitionResult>;
+    /** Flip a profile to manual APN via ONE atomic modify, then reactivate + classify. */
+    transitionToManual(id: ConnectionId, ifname: DeviceIfname, creds: ManualApn): Promise<AutoApnTransitionResult>;
+}

package/dist/backend/nmcli-nm-port.js

@@ -0,0 +1,173 @@
+// The device-exact NetworkManager adapter: a FRESH nmcli-based `NetworkManagerPort`
+// (no reused CeraUI code) with the full nine-field GSM write parity, verify-then-
+// device-disconnect deactivation (never id-only `connection down`), abandoned-lease
+// quiesce, and atomic Auto-APN transitions.
+import { epochMillis } from '../domain/index.js';
+import { connectionId, receipt, } from '../ports/index.js';
+import { AUTO_APN_ADVISORY, classifyActivation, toAutoArgs, toManualArgs, } from './nm-auto-apn.js';
+import { buildProfile, createGsmArgs, patchPairs } from './nm-gsm-fields.js';
+import { parseTerse, runNmcli } from './nmcli-runner.js';
+const READBACK_FIELDS = [
+    'connection.id',
+    'gsm.apn',
+    'gsm.username',
+    'gsm.password',
+    'gsm.password-flags',
+    'gsm.home-only',
+    'gsm.network-id',
+    'gsm.auto-config',
+    'connection.autoconnect',
+    'connection.autoconnect-retries',
+];
+/** Default abandoned-lease TTL: a held quiesce lease older than this auto-releases. */
+const DEFAULT_LEASE_TTL_MS = 60_000;
+export class NmcliNmPort {
+    #runner;
+    #autoApnCapable;
+    #leaseTtlMs;
+    #now;
+    #leases = new Set();
+    constructor(options) {
+        this.#runner = options.runner;
+        this.#autoApnCapable = options.autoApnCapable ?? true;
+        this.#leaseTtlMs = options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS;
+        this.#now = options.now ?? Date.now;
+    }
+    async createGsmProfile(profile) {
+        const result = await runNmcli(this.#runner, createGsmArgs(profile));
+        const uuid = /\(([^)]+)\) successfully added/.exec(result.stdout)?.[1];
+        if (uuid === undefined) {
+            throw new Error(`nmcli connection add failed: ${result.stderr || result.stdout}`);
+        }
+        return this.#requireProfile(connectionId(uuid));
+    }
+    async readGsmProfile(id) {
+        const result = await runNmcli(this.#runner, [
+            '-t',
+            '-f',
+            READBACK_FIELDS.join(','),
+            'connection',
+            'show',
+            id,
+        ]);
+        if (result.exitCode !== 0) {
+            return undefined;
+        }
+        return buildProfile(id, parseTerse(result.stdout));
+    }
+    async updateGsmProfile(id, patch) {
+        const result = await runNmcli(this.#runner, ['connection', 'modify', id, ...patchPairs(patch)]);
+        if (result.exitCode !== 0) {
+            throw new Error(`nmcli connection modify failed: ${result.stderr}`);
+        }
+        return this.#requireProfile(id);
+    }
+    async deleteGsmProfile(id) {
+        await runNmcli(this.#runner, ['connection', 'delete', id]);
+    }
+    async activate(id, ifname) {
+        const result = await runNmcli(this.#runner, ['connection', 'up', id, 'ifname', ifname]);
+        return activationReceipt(result, `activated ${id} on ${ifname}`);
+    }
+    async deactivate(id, ifname) {
+        if ((await this.#activeUuidOn(ifname)) !== id) {
+            return receipt('enabled', 'applied', `${id} not active on ${ifname}; nothing to deactivate`);
+        }
+        const result = await runNmcli(this.#runner, ['device', 'disconnect', ifname]);
+        return activationReceipt(result, `deactivated ${id} on ${ifname}`);
+    }
+    async acquireQuiesceLease(id, ifname) {
+        if ((await this.#activeUuidOn(ifname)) === id) {
+            await runNmcli(this.#runner, ['device', 'disconnect', ifname]);
+        }
+        const lease = {
+            connectionId: id,
+            deviceIfname: ifname,
+            acquiredAt: epochMillis(this.#now()),
+        };
+        this.#leases.add(lease);
+        return lease;
+    }
+    async releaseQuiesceLease(lease) {
+        if (this.#leases.delete(lease)) {
+            await this.#reactivate(lease);
+        }
+    }
+    /** Reactivate every lease held past the TTL — the abandoned-lease watchdog. */
+    async sweepExpiredLeases(now = this.#now()) {
+        for (const lease of [...this.#leases]) {
+            if (now - lease.acquiredAt >= this.#leaseTtlMs) {
+                this.#leases.delete(lease);
+                await this.#reactivate(lease);
+            }
+        }
+    }
+    /** Flip a profile to Auto-APN via ONE atomic modify, then reactivate + classify. */
+    async transitionToAuto(id, ifname) {
+        if (!this.#autoApnCapable) {
+            return {
+                receipt: receipt('connection', 'unsupported', 'Auto-APN requires NetworkManager >= 1.22'),
+                advisory: AUTO_APN_ADVISORY,
+            };
+        }
+        const modify = await runNmcli(this.#runner, toAutoArgs(id));
+        if (modify.exitCode !== 0) {
+            return {
+                receipt: receipt('connection', 'failed', modify.stderr || 'auto-config modify rejected'),
+            };
+        }
+        return this.#reactivateAndClassify(id, ifname, true);
+    }
+    /** Flip a profile to manual APN via ONE atomic modify, then reactivate + classify. */
+    async transitionToManual(id, ifname, creds) {
+        const modify = await runNmcli(this.#runner, toManualArgs(id, creds));
+        if (modify.exitCode !== 0) {
+            return {
+                receipt: receipt('connection', 'failed', modify.stderr || 'manual-apn modify rejected'),
+            };
+        }
+        return this.#reactivateAndClassify(id, ifname, false);
+    }
+    async #reactivateAndClassify(id, ifname, underAuto) {
+        const up = await runNmcli(this.#runner, ['connection', 'up', id, 'ifname', ifname]);
+        return classifyActivation(up, { underAuto });
+    }
+    async #reactivate(lease) {
+        await runNmcli(this.#runner, [
+            'connection',
+            'up',
+            lease.connectionId,
+            'ifname',
+            lease.deviceIfname,
+        ]);
+    }
+    async #activeUuidOn(ifname) {
+        const result = await runNmcli(this.#runner, [
+            '-t',
+            '-f',
+            'UUID,DEVICE',
+            'connection',
+            'show',
+            '--active',
+        ]);
+        for (const line of result.stdout.split('\n')) {
+            const [uuid, device] = line.split(':');
+            if (device === ifname && uuid) {
+                return uuid;
+            }
+        }
+        return undefined;
+    }
+    async #requireProfile(id) {
+        const profile = await this.readGsmProfile(id);
+        if (profile === undefined) {
+            throw new Error(`nmcli: profile ${id} did not read back`);
+        }
+        return profile;
+    }
+}
+function activationReceipt(result, appliedReason) {
+    return result.exitCode === 0
+        ? receipt('enabled', 'applied', appliedReason)
+        : receipt('enabled', 'failed', result.stderr || 'nmcli returned a non-zero exit code');
+}

package/dist/backend/nmcli-runner.d.ts

@@ -0,0 +1,24 @@
+export interface NmcliResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+/**
+ * A runner over nmcli argv. `run` may be synchronous (the stateful test double) or
+ * asynchronous (the real `Bun.spawn` adapter) — the port awaits either way.
+ */
+export interface NmcliRunner {
+    run(argv: readonly string[]): NmcliResult | Promise<NmcliResult>;
+}
+/** Await a runner's result whether it returned synchronously or as a promise. */
+export declare function runNmcli(runner: NmcliRunner, argv: readonly string[]): Promise<NmcliResult>;
+/**
+ * The device-exact runner: spawns the real `nmcli` via Bun. Every argv the port
+ * builds is passed verbatim, so what the tests assert against the stateful stub is
+ * byte-for-byte what runs on the device.
+ */
+export declare class SpawnNmcliRunner implements NmcliRunner {
+    run(argv: readonly string[]): Promise<NmcliResult>;
+}
+/** Parse nmcli terse (`-t`) `key:value` lines into a map, splitting on the first `:`. */
+export declare function parseTerse(stdout: string): Map<string, string>;

package/dist/backend/nmcli-runner.js

@@ -0,0 +1,35 @@
+// The nmcli invocation seam. The shipping adapter spawns the real `nmcli`; tests
+// inject A2.3's stateful in-memory runner (structurally the same `run(argv)`). The
+// port never spawns directly — it only ever talks to an injected `NmcliRunner`, so
+// the exact code path exercised under test is the one that runs on-device.
+/** Await a runner's result whether it returned synchronously or as a promise. */
+export async function runNmcli(runner, argv) {
+    return runner.run(argv);
+}
+/**
+ * The device-exact runner: spawns the real `nmcli` via Bun. Every argv the port
+ * builds is passed verbatim, so what the tests assert against the stateful stub is
+ * byte-for-byte what runs on the device.
+ */
+export class SpawnNmcliRunner {
+    async run(argv) {
+        const proc = Bun.spawn(['nmcli', ...argv], { stdout: 'pipe', stderr: 'pipe' });
+        const [stdout, stderr, exitCode] = await Promise.all([
+            new Response(proc.stdout).text(),
+            new Response(proc.stderr).text(),
+            proc.exited,
+        ]);
+        return { stdout, stderr, exitCode };
+    }
+}
+/** Parse nmcli terse (`-t`) `key:value` lines into a map, splitting on the first `:`. */
+export function parseTerse(stdout) {
+    const settings = new Map();
+    for (const line of stdout.split('\n')) {
+        const separator = line.indexOf(':');
+        if (separator >= 0) {
+            settings.set(line.slice(0, separator), line.slice(separator + 1));
+        }
+    }
+    return settings;
+}

package/dist/backend/observer.d.ts

@@ -0,0 +1,37 @@
+import type { ModemObservationPort, ObservationList, ObservationListener, Unsubscribe } from '../ports/index.js';
+import type { DbusTransport } from '../transport/index.js';
+import { type DecodedManagedObjects } from './managed-objects.js';
+/**
+ * A current-epoch authoritative snapshot, delivered to `onEpochRefresh` AFTER the
+ * epoch guard passes. `epoch` is the owning MM unique bus name; `tree` is the decoded
+ * `GetManagedObjects` payload the snapshot was reconciled from. The Signal.Setup
+ * manager (A3.3) hooks this to (re-)apply cadence per modem per epoch, and the D-Bus
+ * backend uses it to refresh its path→stable-key map.
+ */
+export interface EpochRefreshEvent {
+    readonly epoch: string;
+    readonly tree: DecodedManagedObjects;
+}
+export interface MmDbusObserverOptions {
+    /** The transport to talk D-Bus over (A2.4). The observer connects it on `start()`. */
+    readonly transport: DbusTransport;
+    /** MM bus name override (defaults to `org.freedesktop.ModemManager1`). */
+    readonly destination?: string;
+    /**
+     * Called after EVERY successful current-epoch authoritative snapshot (start,
+     * hot-plug, epoch change, property change) — never for a superseded epoch. The
+     * hook fires whether or not any row changed, so a consumer always sees the live
+     * epoch + tree. It must not throw; a throw is swallowed so it can never break the
+     * observer's refresh loop.
+     */
+    readonly onEpochRefresh?: (event: EpochRefreshEvent) => void;
+}
+export declare class MmDbusObserver implements ModemObservationPort {
+    #private;
+    constructor(options: MmDbusObserverOptions);
+    start(): Promise<ObservationList>;
+    observe(listener: ObservationListener): Unsubscribe;
+    stop(): Promise<void>;
+}
+/** Construct an epoch-scoped ModemManager observer over an A2.4 transport. */
+export declare function createMmDbusObserver(options: MmDbusObserverOptions): MmDbusObserver;