@ceralive/modem-control 1.0.0 → 1.1.0

package/dist/providers/modem-manager/module-operations.js

@@ -0,0 +1,118 @@
+import { epochMillis, runtimePath } from '../../domain/index.js';
+import { resolveFccUnlockCoverage } from '../../fcc/index.js';
+import { advanceGnssFixState, GNSS_OFF } from '../../location/index.js';
+import { createDbusSmsPort } from '../../sms/index.js';
+export class ModemManagerModuleOperations {
+    operations;
+    #options;
+    #smsPorts = new Map();
+    #locationStates = new Map();
+    constructor(options) {
+        this.#options = options;
+        this.operations = {
+            location: {
+                status: async (context) => {
+                    const path = await this.#modemPath(context);
+                    return path === undefined
+                        ? { ok: false, reason: 'modem-not-found' }
+                        : this.#options.location.getLocationStatus(runtimePath(path));
+                },
+                enable: async (context, sources) => {
+                    const path = await this.#modemPath(context);
+                    if (path === undefined)
+                        return this.#unsupportedToggle();
+                    const result = await this.#options.location.enableGnss(runtimePath(path), sources);
+                    if (result.outcome === 'applied') {
+                        this.#setLocationState(context, {
+                            kind: 'gnss-enabled',
+                            at: epochMillis(this.#options.now()),
+                        });
+                    }
+                    return result;
+                },
+                disable: async (context) => {
+                    const path = await this.#modemPath(context);
+                    if (path === undefined)
+                        return this.#unsupportedToggle();
+                    const result = await this.#options.location.disableGnss(runtimePath(path));
+                    if (result.outcome === 'applied')
+                        this.#setLocationState(context, { kind: 'gnss-disabled' });
+                    return result;
+                },
+                readFix: async (context) => {
+                    const path = await this.#modemPath(context);
+                    if (path === undefined)
+                        return { outcome: 'unsupported', reason: 'modem-not-found' };
+                    const read = await this.#options.location.readFix(runtimePath(path));
+                    this.#setLocationState(context, {
+                        kind: 'read',
+                        at: epochMillis(this.#options.now()),
+                        read,
+                    });
+                    return read;
+                },
+                state: (context) => this.#locationStates.get(String(context.physicalModemId)) ?? GNSS_OFF,
+                tick: (context) => this.#setLocationState(context, {
+                    kind: 'tick',
+                    at: epochMillis(this.#options.now()),
+                }),
+            },
+            sms: (context) => this.#sms(context),
+            ussd: options.ussd,
+            initiateUssd: (context, ussdCommand) => this.#ussd(context, (path) => options.ussd.initiate(runtimePath(path), ussdCommand)),
+            respondUssd: (context, ussdResponse) => this.#ussd(context, (path) => options.ussd.respond(runtimePath(path), ussdResponse)),
+            cancelUssd: (context) => this.#ussd(context, (path) => options.ussd.cancel(runtimePath(path))),
+            fccCoverage: resolveFccUnlockCoverage,
+        };
+    }
+    async stop() {
+        for (const port of this.#smsPorts.values())
+            await port.stop();
+        this.#smsPorts.clear();
+        this.#options.ussd.stop();
+    }
+    async #sms(context) {
+        const snapshot = await this.#options.readSnapshot(context);
+        if (!snapshot.ok)
+            return { ok: false, reason: snapshot.reason };
+        if (!snapshot.capabilities.sms)
+            return { ok: false, reason: 'unsupported' };
+        let port = this.#smsPorts.get(snapshot.modemPath);
+        if (port === undefined) {
+            port = createDbusSmsPort({
+                transport: this.#options.transport,
+                modemPath: snapshot.modemPath,
+                destination: this.#options.destination,
+            });
+            this.#smsPorts.set(snapshot.modemPath, port);
+        }
+        return { ok: true, port };
+    }
+    async #ussd(context, run) {
+        const path = await this.#modemPath(context);
+        return path === undefined
+            ? {
+                ok: false,
+                snapshot: this.#options.ussd.snapshot(runtimePath('/')),
+                refusal: 'unsupported',
+            }
+            : run(path);
+    }
+    async #modemPath(context) {
+        const snapshot = await this.#options.readSnapshot(context);
+        return snapshot.ok ? snapshot.modemPath : undefined;
+    }
+    #setLocationState(context, event) {
+        const key = String(context.physicalModemId);
+        const next = advanceGnssFixState(this.#locationStates.get(key) ?? GNSS_OFF, event);
+        this.#locationStates.set(key, next);
+        return next;
+    }
+    #unsupportedToggle() {
+        return {
+            outcome: 'unsupported',
+            reason: 'modem-not-found',
+            enabledSources: new Set(),
+        };
+    }
+}

package/dist/providers/modem-manager/provider.d.ts

@@ -0,0 +1,39 @@
+import { type MmDbusBackend, type QuiesceHook } from '../../backend/index.js';
+import { type BandCertificationCatalog, type BandSku } from '../../band/index.js';
+import { type NormalizedModemObservation } from '../../observations/index.js';
+import type { ObservationListener } from '../../ports/index.js';
+import type { DbusTransport } from '../../transport/index.js';
+import type { ProviderDefinition, ProviderExecutionContext } from '../contracts.js';
+import type { ModemManagerProviderLifecycle, ModemManagerProviderOperations, ModemManagerSnapshotResult } from './types.js';
+export interface ModemManagerProviderOptions {
+    readonly transport: DbusTransport;
+    readonly destination?: string;
+    readonly quiesce?: QuiesceHook;
+    readonly now?: () => number;
+    /**
+     * The band-lock certification catalog. Defaults to the one shipped in this package,
+     * which is EMPTY — so a band write is refused on every device until a human-reviewed
+     * commit adds an entry carrying its bench transcript.
+     */
+    readonly bandCertificationCatalog?: BandCertificationCatalog;
+    /**
+     * The device's SKU, if the embedding process can resolve one.
+     *
+     * ModemManager's `Modem` interface carries `Model` and `Revision` but NO USB
+     * `vid:pid`, and `BandSku` is keyed on all three — so this package structurally
+     * cannot build one from the bus alone, and a partial match would certify a family
+     * no reviewer looked at. With no resolver injected there is no SKU, hence no entry,
+     * hence no band write: fail-closed, which is this module's whole stance.
+     */
+    readonly bandSku?: (context: ProviderExecutionContext) => BandSku | undefined;
+}
+export declare class ModemManagerProvider implements ModemManagerProviderLifecycle {
+    #private;
+    readonly definition: ProviderDefinition<NormalizedModemObservation, ModemManagerProviderOperations>;
+    constructor(options: ModemManagerProviderOptions);
+    start(): ReturnType<MmDbusBackend['start']>;
+    observe(listener: ObservationListener): () => void;
+    stop(): Promise<void>;
+    readSnapshot(context: ProviderExecutionContext): Promise<ModemManagerSnapshotResult>;
+}
+export declare function createModemManagerProvider(options: ModemManagerProviderOptions): ModemManagerProvider;

package/dist/providers/modem-manager/provider.js

@@ -0,0 +1,152 @@
+import { createMmDbusBackend, fetchManagedObjects, MM_BUS_NAME, MmLocation, ModemActor, } from '../../backend/index.js';
+import { BAND_CERTIFICATION_CATALOG, findBandCertification, } from '../../band/index.js';
+import { epochMillis, sourceEpoch, stableKeyFromPhysicalModemId, } from '../../domain/index.js';
+import { unavailableObservation } from '../../observations/index.js';
+import { MmUssd } from '../../ussd/index.js';
+import { mapModemManagerError } from './errors.js';
+import { createGenericOperations } from './generic-operations.js';
+import { ModemManagerModuleOperations } from './module-operations.js';
+import { buildModemManagerSnapshot } from './snapshot.js';
+const PROFILE = 'generic-mm';
+export class ModemManagerProvider {
+    definition;
+    #transport;
+    #destination;
+    #now;
+    #backend;
+    #bandCatalog;
+    #bandSku;
+    #stableKeyByPath = new Map();
+    #moduleOperations;
+    #startPromise;
+    #epoch = 1;
+    constructor(options) {
+        this.#transport = options.transport;
+        this.#destination = options.destination ?? MM_BUS_NAME;
+        this.#now = options.now ?? Date.now;
+        this.#bandCatalog = options.bandCertificationCatalog ?? BAND_CERTIFICATION_CATALOG;
+        this.#bandSku = options.bandSku ?? (() => undefined);
+        const actor = new ModemActor(options.quiesce);
+        const resolveStableKey = (modem) => this.#stableKeyByPath.get(modem) ?? modem;
+        this.#backend = createMmDbusBackend({
+            transport: this.#transport,
+            destination: this.#destination,
+            actor,
+            now: this.#now,
+        });
+        const location = new MmLocation({
+            transport: this.#transport,
+            actor,
+            destination: this.#destination,
+            resolveStableKey,
+            now: this.#now,
+        });
+        const ussd = new MmUssd({
+            transport: this.#transport,
+            actor,
+            destination: this.#destination,
+            resolveStableKey,
+        });
+        this.#moduleOperations = new ModemManagerModuleOperations({
+            transport: this.#transport,
+            destination: this.#destination,
+            location,
+            ussd,
+            now: this.#now,
+            readSnapshot: (context) => this.readSnapshot(context),
+        });
+        const operations = {
+            access: 'read-write',
+            ...createGenericOperations({
+                backend: this.#backend,
+                readSnapshot: (context) => this.readSnapshot(context),
+            }),
+            ...this.#moduleOperations.operations,
+        };
+        this.definition = {
+            id: 'modemmanager',
+            profileVersion: '1',
+            eligibleTransports: ['modemmanager'],
+            passiveMatchers: [],
+            unauthenticatedProbes: [
+                { id: 'object-manager-modem', run: (request) => this.#probe(request) },
+            ],
+            capabilityReaders: [
+                { id: 'runtime-modem-interface', read: (context) => this.#capability(context) },
+            ],
+            observe: (context) => this.#observeNormalized(context),
+            operations: () => operations,
+            contractFixtures: [],
+        };
+    }
+    start() {
+        this.#startPromise ??= this.#backend.start();
+        return this.#startPromise;
+    }
+    observe(listener) {
+        return this.#backend.observe(listener);
+    }
+    async stop() {
+        await this.#moduleOperations.stop();
+        await this.#backend.stop();
+    }
+    async readSnapshot(context) {
+        try {
+            await this.start();
+            const tree = await fetchManagedObjects(this.#transport, this.#destination);
+            const snapshot = buildModemManagerSnapshot(tree, context, this.#now, this.#epoch, this.#bandCertification(context));
+            if (snapshot === undefined)
+                return { ok: false, reason: 'not-found' };
+            this.#stableKeyByPath.set(snapshot.modemPath, `modem:${context.physicalModemId}`);
+            return { ok: true, ...snapshot };
+        }
+        catch (error) {
+            return { ok: false, reason: mapModemManagerError(error).reason };
+        }
+    }
+    #bandCertification(context) {
+        const sku = this.#bandSku(context);
+        return sku === undefined ? undefined : findBandCertification(this.#bandCatalog, sku);
+    }
+    async #probe(request) {
+        const snapshot = await this.readSnapshot({ ...request, profile: PROFILE });
+        return {
+            signal: snapshot.ok
+                ? 'match'
+                : snapshot.reason === 'not-found'
+                    ? 'mismatch'
+                    : 'unknown',
+            strength: 'strong',
+            profiles: [PROFILE],
+            detail: snapshot.ok ? 'runtime-modem-interface-present' : snapshot.reason,
+        };
+    }
+    async #capability(context) {
+        const snapshot = await this.readSnapshot(context);
+        return {
+            signal: snapshot.ok
+                ? 'match'
+                : snapshot.reason === 'not-found'
+                    ? 'mismatch'
+                    : 'unknown',
+            strength: 'strong',
+            detail: snapshot.ok ? 'generic-controls-derived-from-runtime-properties' : snapshot.reason,
+        };
+    }
+    async #observeNormalized(context) {
+        const snapshot = await this.readSnapshot(context);
+        if (snapshot.ok)
+            return [snapshot.observation];
+        return [
+            unavailableObservation('modemmanager', {
+                stableKey: stableKeyFromPhysicalModemId(context.physicalModemId),
+                generation: context.generation,
+                sourceEpoch: sourceEpoch(this.#epoch),
+                observedAt: epochMillis(this.#now()),
+            }, snapshot.reason === 'not-found' ? 'device-absent' : 'provider-unavailable'),
+        ];
+    }
+}
+export function createModemManagerProvider(options) {
+    return new ModemManagerProvider(options);
+}

package/dist/providers/modem-manager/snapshot.d.ts

@@ -0,0 +1,5 @@
+import { type DecodedManagedObjects } from '../../backend/managed-objects.js';
+import { type BandCertificationEntry } from '../../band/index.js';
+import type { ProviderExecutionContext } from '../contracts.js';
+import type { ModemManagerProviderSnapshot } from './types.js';
+export declare function buildModemManagerSnapshot(tree: DecodedManagedObjects, context: ProviderExecutionContext, now: () => number, epoch: number, bandCertificationEntry: BandCertificationEntry | undefined): ModemManagerProviderSnapshot | undefined;

package/dist/providers/modem-manager/snapshot.js

@@ -0,0 +1,204 @@
+import { MODEM_IFACE, MODEM_LOCATION_IFACE, MODEM3GPP_IFACE, MODEM3GPP_USSD_IFACE, SIM_IFACE, } from '../../backend/constants.js';
+import { findInterface, pathsWithInterface, propValue, } from '../../backend/managed-objects.js';
+import { decodeBandList } from '../../band/index.js';
+import { MESSAGING_IFACE } from '../../capability/index.js';
+import { decodeStateFailedReason, epochMillis, sourceEpoch, stableKeyFromPhysicalModemId, } from '../../domain/index.js';
+import { readSimPresence } from '../../hardware/router-parsers.js';
+import { normalizeModemManagerObservation } from '../../observations/index.js';
+import { describeBandWriteCertification, readRadioModeTruth } from '../../radio/index.js';
+const SIGNAL_IFACE = `${MODEM_IFACE}.Signal`;
+function rawValue(value) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    if (Array.isArray(value)) {
+        const result = [];
+        for (const item of value) {
+            const decoded = rawValue(item);
+            if (decoded !== undefined)
+                result.push(decoded);
+        }
+        return result;
+    }
+    return undefined;
+}
+function propsRecord(props) {
+    if (props === undefined)
+        return undefined;
+    const record = {};
+    for (const [name, wrapped] of props) {
+        const decoded = rawValue(wrapped.value);
+        if (decoded !== undefined)
+            record[name] = decoded;
+    }
+    return record;
+}
+function tuple(value) {
+    if (!Array.isArray(value))
+        return [0, 0];
+    const allowed = value[0];
+    const preferred = value[1];
+    return [typeof allowed === 'number' ? allowed : 0, typeof preferred === 'number' ? preferred : 0];
+}
+function modePairs(value) {
+    if (!Array.isArray(value))
+        return [];
+    const result = [];
+    for (const candidate of value) {
+        const [allowed, preferred] = tuple(candidate);
+        if (allowed > 0)
+            result.push({ allowed, preferred });
+    }
+    return result;
+}
+/**
+ * A `DbusValue` as the retention layer keeps it.
+ *
+ * `rawValue` already produces exactly this for a struct (an array of its members), so
+ * `SupportedModes` and `CurrentModes` reach the verbatim decoder in the same shape the
+ * diagnostics block retains — one representation, so the two cannot disagree.
+ */
+function structValue(value) {
+    return value === undefined ? undefined : rawValue(value);
+}
+function signalState(modem, signal) {
+    const quality = tuple(propValue(modem, 'SignalQuality'));
+    return {
+        ...(quality[0] >= 0 ? { quality: quality[0] } : {}),
+        ...(Array.isArray(propValue(modem, 'SignalQuality')) ? { recent: quality[1] !== 0 } : {}),
+        extendedAvailable: signal !== undefined,
+    };
+}
+function simState(tree, modem) {
+    const activePath = propValue(modem, 'Sim');
+    const slots = propValue(modem, 'SimSlots');
+    const paths = Array.isArray(slots)
+        ? slots.filter((value) => typeof value === 'string' && value !== '/')
+        : [];
+    const active = typeof activePath === 'string' ? findInterface(tree, activePath, SIM_IFACE) : undefined;
+    const lockRequired = propValue(modem, 'UnlockRequired');
+    const rawFailedReason = propValue(modem, 'StateFailedReason');
+    const failedReason = typeof rawFailedReason === 'number'
+        ? decodeStateFailedReason(rawFailedReason)
+        : typeof rawFailedReason === 'string'
+            ? rawFailedReason
+            : undefined;
+    const primarySlot = propValue(modem, 'PrimarySimSlot');
+    const simType = propValue(active, 'SimType');
+    const esimStatus = propValue(active, 'EsimStatus');
+    const reading = readSimPresence({
+        ...(typeof activePath === 'string' ? { sim: activePath } : {}),
+        ...(paths.length > 0 ? { simSlots: paths } : {}),
+        ...(failedReason === undefined ? {} : { failedReason }),
+    });
+    return {
+        // POSITIVE evidence only: an exported SIM object path proves a SIM. Its ABSENCE
+        // proves nothing — `presence` below is the answer to "is there a SIM", and it
+        // says `unknown` unless the modem stated `sim-missing` itself.
+        present: typeof activePath === 'string' && activePath !== '/',
+        presence: reading.presence,
+        presenceEvidence: reading.evidence,
+        slotCount: paths.length,
+        primarySlot: typeof primarySlot === 'number' ? primarySlot : 0,
+        ...(typeof lockRequired === 'number' ? { lockRequired } : {}),
+        ...(typeof simType === 'number' ? { simType } : {}),
+        ...(typeof esimStatus === 'number' ? { esimStatus } : {}),
+    };
+}
+function radioPower(value) {
+    switch (value) {
+        case 1:
+            return 'off';
+        case 2:
+            return 'low';
+        case 3:
+            return 'on';
+        default:
+            return 'unknown';
+    }
+}
+function hasProperty(props, name) {
+    return props.some(([property]) => property === name);
+}
+function findModemPath(tree, context) {
+    const [kind, ...parts] = String(context.physicalModemId).split(':');
+    const expected = parts.join(':');
+    for (const path of pathsWithInterface(tree, MODEM_IFACE)) {
+        const modem = findInterface(tree, path, MODEM_IFACE);
+        const candidates = kind === 'serial'
+            ? [propValue(modem, 'DeviceIdentifier')]
+            : [propValue(modem, 'Device'), propValue(modem, 'Physdev')];
+        if (candidates.some((candidate) => candidate === expected))
+            return path;
+    }
+    return undefined;
+}
+export function buildModemManagerSnapshot(tree, context, now, epoch, bandCertificationEntry) {
+    const modemPath = findModemPath(tree, context);
+    if (modemPath === undefined)
+        return undefined;
+    const modem = findInterface(tree, modemPath, MODEM_IFACE);
+    if (modem === undefined)
+        return undefined;
+    const modem3gpp = findInterface(tree, modemPath, MODEM3GPP_IFACE);
+    const signal = findInterface(tree, modemPath, SIGNAL_IFACE);
+    const activePath = propValue(modem, 'Sim');
+    const sim = typeof activePath === 'string' ? findInterface(tree, activePath, SIM_IFACE) : undefined;
+    const interfaces = tree.find(([path]) => path === modemPath)?.[1] ?? [];
+    const interfaceNames = new Set(interfaces.map(([name]) => name));
+    const slots = propValue(modem, 'SimSlots');
+    const bandCertification = describeBandWriteCertification({
+        entry: bandCertificationEntry,
+        supported: decodeBandList(propValue(modem, 'SupportedBands')),
+    });
+    const capabilities = {
+        modeRead: hasProperty(modem, 'CurrentModes'),
+        modeWrite: hasProperty(modem, 'CurrentModes'),
+        bandRead: hasProperty(modem, 'SupportedBands'),
+        bandWrite: hasProperty(modem, 'SupportedBands') &&
+            bandCertification.satisfied &&
+            bandCertification.offerable.length > 0,
+        signalRead: hasProperty(modem, 'SignalQuality') || signal !== undefined,
+        simRead: hasProperty(modem, 'Sim') || hasProperty(modem, 'SimSlots'),
+        multiSim: Array.isArray(slots) && slots.filter((entry) => entry !== '/').length > 1,
+        location: interfaceNames.has(MODEM_LOCATION_IFACE),
+        sms: interfaceNames.has(MESSAGING_IFACE),
+        ussd: interfaceNames.has(MODEM3GPP_USSD_IFACE),
+        powerRead: hasProperty(modem, 'PowerState'),
+    };
+    const [allowed, preferred] = tuple(propValue(modem, 'CurrentModes'));
+    const modeTruth = readRadioModeTruth({
+        currentModes: structValue(propValue(modem, 'CurrentModes')),
+        supportedModes: structValue(propValue(modem, 'SupportedModes')),
+    });
+    const normalizationContext = {
+        stableKey: stableKeyFromPhysicalModemId(context.physicalModemId),
+        generation: context.generation,
+        sourceEpoch: sourceEpoch(epoch),
+        observedAt: epochMillis(now()),
+    };
+    // The struct properties are handed to normalization VERBATIM — `CurrentModes` as its
+    // `(uu)` pair, `SignalQuality` as its `(ub)` pair. Flattening them here (which this
+    // did) kept the first member and dropped the preferred mode and the recency flag
+    // before the diagnostics block ever saw them, which is a drop no downstream layer
+    // can undo. The normalizer reads either shape.
+    const modemRaw = propsRecord(modem) ?? {};
+    return {
+        modemPath,
+        capabilities,
+        bandCertification,
+        radio: {
+            current: { allowed, preferred },
+            supported: modePairs(propValue(modem, 'SupportedModes')),
+            truth: modeTruth,
+        },
+        signal: signalState(modem, signal),
+        sim: simState(tree, modem),
+        power: radioPower(propValue(modem, 'PowerState')),
+        observation: normalizeModemManagerObservation({
+            modem: modemRaw,
+            ...(modem3gpp === undefined ? {} : { modem3gpp: propsRecord(modem3gpp) ?? {} }),
+            ...(sim === undefined ? {} : { sim: propsRecord(sim) ?? {} }),
+            ...(signal === undefined ? {} : { signal: propsRecord(signal) ?? {} }),
+        }, normalizationContext),
+    };
+}

package/dist/providers/modem-manager/types.d.ts

@@ -0,0 +1,135 @@
+import type { DesiredRadio, ObservationEnvelope, OperationDescriptor, OperationResult, RadioPower } from '../../domain/index.js';
+import type { SimPresence, SimPresenceEvidence } from '../../hardware/router-parsers.js';
+import type { GnssFixState } from '../../location/index.js';
+import type { NormalizedModemObservation } from '../../observations/index.js';
+import type { FixRead, GnssSource, LocationStatusResult, LocationToggleResult, ModemBands, ObservationList, ObservationListener, SmsObservationPort } from '../../ports/index.js';
+import type { BandWriteCertification, ModeSelection, RadioModeTruth } from '../../radio/index.js';
+import type { MmUssd, UssdVerbResult } from '../../ussd/index.js';
+import type { ProviderExecutionContext, ProviderOperationsSurface } from '../contracts.js';
+import type { ModemManagerRefusalReason } from './errors.js';
+export type ModemManagerCapabilities = {
+    readonly modeRead: boolean;
+    readonly modeWrite: boolean;
+    readonly bandRead: boolean;
+    readonly bandWrite: boolean;
+    readonly signalRead: boolean;
+    readonly simRead: boolean;
+    readonly multiSim: boolean;
+    readonly location: boolean;
+    readonly sms: boolean;
+    readonly ussd: boolean;
+    readonly powerRead: boolean;
+};
+export type ModemManagerRadioState = {
+    readonly current: {
+        readonly allowed: number;
+        readonly preferred: number;
+    };
+    readonly supported: readonly {
+        readonly allowed: number;
+        readonly preferred: number;
+    }[];
+    /**
+     * The SAME properties decoded without loss — `preferred: 'none'` stays `none`, an
+     * unfamiliar mode bit stays offerable as `unknown-combination`, and a member that
+     * is not a `(uu)` lands in `undecodable` rather than vanishing. `supported` above
+     * is the pre-existing raw-mask view and DROPS a zero-allowed member; this one does
+     * not, which is the whole point of carrying both.
+     */
+    readonly truth: RadioModeTruth;
+};
+export type ModemManagerSignalState = {
+    readonly quality?: number;
+    readonly recent?: boolean;
+    readonly extendedAvailable: boolean;
+};
+export type ModemManagerSimState = {
+    /**
+     * The modem exports an ACTIVE SIM object path. `true` is positive evidence of a
+     * SIM; `false` is NOT evidence of absence — read `presence` for that.
+     */
+    readonly present: boolean;
+    /** `absent` only ever comes from `StateFailedReason: sim-missing`. */
+    readonly presence: SimPresence;
+    readonly presenceEvidence: SimPresenceEvidence;
+    readonly slotCount: number;
+    readonly primarySlot: number;
+    readonly lockRequired?: number;
+    readonly simType?: number;
+    readonly esimStatus?: number;
+};
+export type ModemManagerProviderSnapshot = {
+    readonly modemPath: string;
+    readonly capabilities: ModemManagerCapabilities;
+    readonly radio: ModemManagerRadioState;
+    /** The band-lock gate for THIS device, resolved from the shipped certification catalog. */
+    readonly bandCertification: BandWriteCertification;
+    readonly signal: ModemManagerSignalState;
+    readonly sim: ModemManagerSimState;
+    readonly power: RadioPower;
+    readonly observation: ObservationEnvelope<NormalizedModemObservation>;
+};
+export type ModemManagerSnapshotResult = ({
+    readonly ok: true;
+} & ModemManagerProviderSnapshot) | {
+    readonly ok: false;
+    readonly reason: ModemManagerRefusalReason;
+};
+export interface ContextReadOperation<O> {
+    readonly descriptor: OperationDescriptor<never, O>;
+    read(context: ProviderExecutionContext): Promise<OperationResult<O>>;
+}
+export interface ContextWriteOperation<I, O> {
+    /** The shape-only descriptor: what this operation is, before any device answered. */
+    readonly descriptor: OperationDescriptor<I, O>;
+    /**
+     * The descriptor as the LIVE device entitles it.
+     *
+     * A static descriptor cannot carry a device's own catalog, so it cannot say which
+     * mode combinations this modem advertises or whether this SKU's band lock is
+     * certified. Those are exactly the facts a consumer needs before it offers a
+     * control, so they are read here instead of being inferred from a capability flag.
+     */
+    describe(context: ProviderExecutionContext): Promise<OperationDescriptor<I, O>>;
+    read(context: ProviderExecutionContext): Promise<OperationResult<O>>;
+    write(context: ProviderExecutionContext, input: I): Promise<OperationResult<O>>;
+}
+export type SmsPortResult = {
+    readonly ok: true;
+    readonly port: SmsObservationPort;
+} | {
+    readonly ok: false;
+    readonly reason: ModemManagerRefusalReason;
+};
+export interface ModemManagerProviderOperations extends ProviderOperationsSurface {
+    readonly radio: ContextWriteOperation<DesiredRadio, ModemManagerRadioState>;
+    /**
+     * The modem's OWN mode vocabulary — an advertised `(allowed, preferred)` pair,
+     * selected verbatim. Separate from `radio` because `DesiredRadio` is an ordered RAT
+     * preference and cannot express `preferred: none`, which real hardware advertises.
+     */
+    readonly modes: ContextWriteOperation<ModeSelection, RadioModeTruth>;
+    readonly bands: ContextWriteOperation<readonly string[], ModemBands>;
+    readonly signal: ContextReadOperation<ModemManagerSignalState>;
+    readonly sim: ContextReadOperation<ModemManagerSimState>;
+    readonly power: ContextReadOperation<RadioPower>;
+    readonly location: {
+        status(context: ProviderExecutionContext): Promise<LocationStatusResult>;
+        enable(context: ProviderExecutionContext, sources: readonly GnssSource[]): Promise<LocationToggleResult>;
+        disable(context: ProviderExecutionContext): Promise<LocationToggleResult>;
+        readFix(context: ProviderExecutionContext): Promise<FixRead>;
+        state(context: ProviderExecutionContext): GnssFixState;
+        tick(context: ProviderExecutionContext): GnssFixState;
+    };
+    sms(context: ProviderExecutionContext): Promise<SmsPortResult>;
+    readonly ussd: MmUssd;
+    initiateUssd(context: ProviderExecutionContext, ussdCommand: string): Promise<UssdVerbResult>;
+    respondUssd(context: ProviderExecutionContext, ussdResponse: string): Promise<UssdVerbResult>;
+    cancelUssd(context: ProviderExecutionContext): Promise<UssdVerbResult>;
+    readonly fccCoverage: (vid: string | undefined, pid: string | undefined) => 'present' | 'absent' | 'unknown';
+}
+export interface ModemManagerProviderLifecycle {
+    start(): Promise<ObservationList>;
+    observe(listener: ObservationListener): () => void;
+    stop(): Promise<void>;
+}

package/dist/providers/modem-manager/types.js

@@ -0,0 +1 @@
+export {};