@ceralive/modem-control 0.2.0 → 1.1.0

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;

package/dist/backend/observer.js

@@ -0,0 +1,219 @@
+// The epoch-scoped ModemManager observer.
+//
+// `MmDbusObserver` implements the read-only `ModemObservationPort` over the A2.4
+// transport, tested against the A2.3 fake. `start()` connects, subscribes to the four
+// lifecycle signals, THEN takes the first authoritative `GetManagedObjects` snapshot —
+// reconciling any signal that raced in between.
+//
+// SAFETY-CRITICAL — epoch-scoped removal (draft §Oracle round-3 #5). An "epoch" is one
+// continuous ownership period of the MM bus name, tracked via `NameOwnerChanged`. A
+// modem is REMOVED only when it is missing from a CURRENT-epoch authoritative snapshot.
+// Owner loss, bus disconnect, and any signal whose `sender` is not the current owner
+// (an OLD-epoch straggler) never remove a modem — they only ever mark it
+// `sourceUnavailable`. The false-removal class is dead by construction: even the
+// `ObservationList` failure arm retains its rows. Row bookkeeping lives in
+// `ObservationRowStore`; this file owns epoch tracking, subscriptions, and refresh.
+import { DBUS_DESTINATION, DBUS_IFACE, DBUS_PATH, MM_BUS_NAME, MM_ROOT_PATH, OBJECT_MANAGER_IFACE, PROPERTIES_IFACE, } from './constants.js';
+import { asManagedObjects } from './managed-objects.js';
+import { ObservationRowStore } from './row-store.js';
+export class MmDbusObserver {
+    #transport;
+    #destination;
+    #onEpochRefresh;
+    #store = new ObservationRowStore();
+    #listeners = new Set();
+    #subscriptions = [];
+    #currentOwner;
+    #started = false;
+    #stopped = false;
+    #priming = false;
+    #refreshDuringPrime = false;
+    #refreshing = false;
+    #refreshQueued = false;
+    #onDisconnected = () => this.#handleSourceGone('source-unavailable');
+    #onReconnected = () => {
+        void this.#adoptCurrentOwner();
+    };
+    constructor(options) {
+        this.#transport = options.transport;
+        this.#destination = options.destination ?? MM_BUS_NAME;
+        this.#onEpochRefresh = options.onEpochRefresh;
+    }
+    async start() {
+        if (this.#started) {
+            return this.#store.list();
+        }
+        this.#started = true;
+        this.#priming = true;
+        await this.#transport.connect();
+        this.#transport.on('disconnected', this.#onDisconnected);
+        this.#transport.on('reconnected', this.#onReconnected);
+        await this.#subscribeAll();
+        await this.#adoptCurrentOwner();
+        this.#priming = false;
+        if (this.#refreshDuringPrime) {
+            this.#refreshDuringPrime = false;
+            this.#scheduleRefresh();
+        }
+        return this.#store.list();
+    }
+    observe(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    async stop() {
+        if (this.#stopped) {
+            return;
+        }
+        this.#stopped = true;
+        this.#transport.off('disconnected', this.#onDisconnected);
+        this.#transport.off('reconnected', this.#onReconnected);
+        const subs = this.#subscriptions.splice(0);
+        await Promise.all(subs.map((sub) => sub.unsubscribe().catch(() => undefined)));
+        this.#listeners.clear();
+    }
+    // ── signal subscription ────────────────────────────────────────────────────────
+    async #subscribeAll() {
+        const om = { interface: OBJECT_MANAGER_IFACE, path: MM_ROOT_PATH };
+        this.#subscriptions.push(await this.#transport.subscribeSignal({ ...om, member: 'InterfacesAdded' }, (event) => this.#onObjectSignal(event)), await this.#transport.subscribeSignal({ ...om, member: 'InterfacesRemoved' }, (event) => this.#onObjectSignal(event)), await this.#transport.subscribeSignal({ interface: PROPERTIES_IFACE, member: 'PropertiesChanged' }, (event) => this.#onObjectSignal(event)), await this.#transport.subscribeSignal({ interface: DBUS_IFACE, member: 'NameOwnerChanged' }, (event) => this.#onNameOwnerChanged(event)));
+    }
+    // ── epoch tracking ───────────────────────────────────────────────────────────
+    async #adoptCurrentOwner() {
+        const owner = await this.#queryOwner();
+        if (owner === undefined) {
+            this.#handleSourceGone('source-unavailable');
+            return;
+        }
+        this.#currentOwner = owner;
+        await this.#runRefresh(owner);
+    }
+    async #queryOwner() {
+        try {
+            const reply = await this.#transport.callMethod({
+                destination: DBUS_DESTINATION,
+                path: DBUS_PATH,
+                interface: DBUS_IFACE,
+                member: 'GetNameOwner',
+                signature: 's',
+                args: [MM_BUS_NAME],
+            });
+            const owner = reply.body[0];
+            return typeof owner === 'string' && owner.length > 0 ? owner : undefined;
+        }
+        catch {
+            // NameHasNoOwner (or a transient failure) → no current epoch yet.
+            return undefined;
+        }
+    }
+    #onNameOwnerChanged(event) {
+        if (event.body[0] !== MM_BUS_NAME) {
+            return;
+        }
+        const newOwner = typeof event.body[2] === 'string' ? event.body[2] : '';
+        if (newOwner.length === 0) {
+            // Owner lost — stale, never a removal.
+            this.#handleSourceGone('source-unavailable');
+            return;
+        }
+        if (newOwner === this.#currentOwner) {
+            return;
+        }
+        // New epoch: everything goes stale until the fresh snapshot restores it.
+        if (this.#store.markUnavailable('source-unavailable')) {
+            this.#emit();
+        }
+        this.#currentOwner = newOwner;
+        this.#scheduleRefresh();
+    }
+    #onObjectSignal(event) {
+        // Epoch guard: a signal from anyone but the current owner is an OLD-epoch
+        // straggler and must never drive a removal (draft §Oracle round-3 #5).
+        if (this.#currentOwner === undefined || event.sender !== this.#currentOwner) {
+            return;
+        }
+        if (this.#priming) {
+            this.#refreshDuringPrime = true;
+            return;
+        }
+        this.#scheduleRefresh();
+    }
+    // ── authoritative refresh ──────────────────────────────────────────────────────
+    #scheduleRefresh() {
+        const owner = this.#currentOwner;
+        if (owner === undefined || this.#stopped) {
+            return;
+        }
+        if (this.#refreshing) {
+            this.#refreshQueued = true;
+            return;
+        }
+        void this.#runRefresh(owner);
+    }
+    async #runRefresh(epochOwner) {
+        this.#refreshing = true;
+        try {
+            const reply = await this.#transport.callMethod({
+                destination: this.#destination,
+                path: MM_ROOT_PATH,
+                interface: OBJECT_MANAGER_IFACE,
+                member: 'GetManagedObjects',
+            });
+            // Late reply from a superseded epoch — discard (draft §Oracle round-3 #5).
+            if (this.#currentOwner !== epochOwner || this.#stopped) {
+                return;
+            }
+            const tree = asManagedObjects(reply.body[0]);
+            const rowsChanged = this.#store.reconcile(tree);
+            const healthChanged = this.#store.markHealthy();
+            this.#notifyEpochRefresh(epochOwner, tree);
+            if (rowsChanged || healthChanged) {
+                this.#emit();
+            }
+        }
+        catch {
+            if (this.#currentOwner === epochOwner && !this.#stopped) {
+                this.#markUnavailable('bus-error');
+            }
+        }
+        finally {
+            this.#refreshing = false;
+            if (this.#refreshQueued && !this.#stopped) {
+                this.#refreshQueued = false;
+                this.#scheduleRefresh();
+            }
+        }
+    }
+    // ── source-unavailable transitions ─────────────────────────────────────────────
+    #handleSourceGone(reason) {
+        this.#currentOwner = undefined;
+        this.#markUnavailable(reason);
+    }
+    #markUnavailable(reason) {
+        if (this.#store.markUnavailable(reason)) {
+            this.#emit();
+        }
+    }
+    #notifyEpochRefresh(epoch, tree) {
+        if (this.#onEpochRefresh === undefined) {
+            return;
+        }
+        try {
+            this.#onEpochRefresh({ epoch, tree });
+        }
+        catch {
+            // A consumer's hook must never break the observer's refresh loop.
+        }
+    }
+    #emit() {
+        const list = this.#store.list();
+        for (const listener of [...this.#listeners]) {
+            listener(list);
+        }
+    }
+}
+/** Construct an epoch-scoped ModemManager observer over an A2.4 transport. */
+export function createMmDbusObserver(options) {
+    return new MmDbusObserver(options);
+}

package/dist/backend/power-contract.d.ts

@@ -0,0 +1,49 @@
+import type { EpochMillis } from '../domain/index.js';
+/** How a board can power-cycle a modem. Only `none` is implemented in Phase A. */
+export type PowerCapabilityKind = 'none' | 'gpio-cut' | 'pwrkey-pulse' | 'usb-hub-port-cycle';
+/**
+ * The USB data mode a modem should re-enumerate into after a power cycle. A4.2 owns
+ * the certified USB-mode catalog; the power contract only records the operator's
+ * preferred post-cycle enumeration mode.
+ */
+export type PreferredUsbMode = 'qmi' | 'mbim' | 'ecm-ncm' | 'rndis' | 'router-ethernet';
+/** A board's modem power-control capability description. */
+export interface PowerCapability {
+    readonly power: PowerCapabilityKind;
+    /** The board can pulse a USB-level reset on the modem's port. */
+    readonly usbReset?: boolean;
+    /** How long to wait for the modem to re-enumerate after a cycle. */
+    readonly enumerationTimeoutMs: number;
+    /** Which USB mode to prefer when the modem re-enumerates (A4.2 catalog vocabulary). */
+    readonly preferredUsbMode?: PreferredUsbMode;
+}
+/** The Phase-A capability: no board power control exists — a no-op. */
+export declare const NONE_POWER_CAPABILITY: PowerCapability;
+/** Outcome of asking the power hook to cycle a modem. */
+export interface PowerCycleResult {
+    readonly status: 'applied' | 'unsupported' | 'failed';
+    readonly reason: string;
+}
+/** The minimal context handed to the power hook. */
+export interface PowerCycleContext {
+    readonly stableKey: string;
+    readonly at: EpochMillis;
+}
+/**
+ * The pluggable power-cycle hook (recovery ladder rung 4). Phase A ships only the
+ * `none` no-op; a real GPIO / PWRKEY / USB-hub implementation is hardware-gated and
+ * injected later without changing the ladder.
+ */
+export interface PowerHook {
+    readonly capability: PowerCapability;
+    cycle(context: PowerCycleContext): Promise<PowerCycleResult>;
+}
+/**
+ * Build a Phase-A power hook for `capability`. EVERY capability returns
+ * `unsupported`: `none` because there is nothing to cut, and every real mechanism
+ * because its hardware driver is not implemented yet — the contract field exists so
+ * a board can DECLARE the capability, but rung 4 never actuates in Phase A.
+ */
+export declare function unsupportedPowerHook(capability: PowerCapability): PowerHook;
+/** The Phase-A default power hook: describes `none` and always returns `unsupported`. */
+export declare const NONE_POWER_HOOK: PowerHook;