@ceralive/modem-control 1.0.0 → 1.2.0

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

@@ -0,0 +1,155 @@
+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),
+                ...(options.runtimeComposition === undefined
+                    ? {}
+                    : { runtimeComposition: options.runtimeComposition }),
+            }),
+            ...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/runtime-composition-operation.d.ts

@@ -0,0 +1,32 @@
+import { type AtCommandSender, type UsbModeTransitionOutcome } from '../../backend/index.js';
+import { type RuntimeCompositionCapability, type RuntimeCompositionMode } from '../../usb-mode/index.js';
+import type { ProviderExecutionContext } from '../contracts.js';
+import type { ContextWriteOperation } from './types.js';
+export declare const RUNTIME_COMPOSITION_SUPPRESSIONS: readonly ['unknown-vendor', 'no-return-path', 'blocked-by-state', 'provisioning-disabled'];
+export type RuntimeCompositionSuppression = (typeof RUNTIME_COMPOSITION_SUPPRESSIONS)[number];
+export type RuntimeCompositionState = {
+    readonly status: 'available';
+    readonly current: RuntimeCompositionMode;
+    readonly enumerated: readonly RuntimeCompositionMode[];
+    readonly offerable: readonly RuntimeCompositionMode[];
+} | {
+    readonly status: 'suppressed';
+    readonly reason: RuntimeCompositionSuppression;
+    readonly detail: string;
+    readonly current: RuntimeCompositionMode | null;
+    readonly enumerated: readonly RuntimeCompositionMode[];
+    readonly offerable: readonly [];
+};
+export type RuntimeCompositionOperationDeps = {
+    readonly vendor: (context: ProviderExecutionContext) => string | Promise<string>;
+    readonly provisioningEnabled: (context: ProviderExecutionContext) => boolean | Promise<boolean>;
+    readonly blockedReason: (context: ProviderExecutionContext) => string | undefined | Promise<string | undefined>;
+    readonly atSender: AtCommandSender;
+    readonly transition: (context: ProviderExecutionContext, capability: Extract<RuntimeCompositionCapability, {
+        readonly status: 'available';
+    }>, target: RuntimeCompositionMode) => Promise<UsbModeTransitionOutcome>;
+};
+export interface RuntimeCompositionOperation extends ContextWriteOperation<RuntimeCompositionMode, RuntimeCompositionState> {
+    capability(context: ProviderExecutionContext): Promise<RuntimeCompositionState>;
+}
+export declare function createRuntimeCompositionOperation(deps: RuntimeCompositionOperationDeps | undefined): RuntimeCompositionOperation;

package/dist/providers/modem-manager/runtime-composition-operation.js

@@ -0,0 +1,151 @@
+import { AtCommandLease, computeAtAllowlist, } from '../../backend/index.js';
+import { classifyOperationCompletion, defineOperationDescriptor, } from '../../domain/index.js';
+import { isRuntimeCompositionVendor, RUNTIME_COMPOSITION_QUERY_REGISTRY, resolveRuntimeCompositionCapability, } from '../../usb-mode/index.js';
+export const RUNTIME_COMPOSITION_SUPPRESSIONS = [
+    'unknown-vendor',
+    'no-return-path',
+    'blocked-by-state',
+    'provisioning-disabled',
+];
+const OPERATION_ID = 'modemmanager.usb-composition';
+function suppressed(reason, detail, capability) {
+    return {
+        status: 'suppressed',
+        reason,
+        detail,
+        current: capability?.current ?? null,
+        enumerated: capability?.enumerated ?? [],
+        offerable: [],
+    };
+}
+function descriptorFor(state) {
+    const available = state.status === 'available';
+    return defineOperationDescriptor({
+        id: OPERATION_ID,
+        support: {
+            read: { supported: true },
+            write: available ? { supported: true } : { supported: false, reason: state.reason },
+        },
+        authority: 'provider',
+        provider: 'modemmanager',
+        constraints: {
+            kind: 'allowed-values',
+            values: available ? state.offerable : [],
+        },
+        livePreconditions: [
+            'modem-present',
+            'runtime-interface-present',
+            'identity-confident',
+            'streaming-interlock-open',
+        ],
+        availability: available ? { state: 'available' } : { state: 'refused', reason: state.reason },
+        mutationImpact: 'disruptive',
+        retryClass: 'never',
+        readback: {
+            required: true,
+            reason: 'device-reported-composition',
+            matches: (input, value) => value.status === 'available' && Object.is(input, value.current),
+        },
+        rollback: { required: true, reason: 'restore-previous-composition' },
+        journal: { required: true, reason: 'composition-reenumeration' },
+        admission: { required: true, reason: 'provider-mutation' },
+        evidence: { profiles: ['generic-mm'], firmware: [] },
+        confidence: available ? 'high' : 'unknown',
+    });
+}
+function result(context, completion) {
+    return classifyOperationCompletion({
+        operation: 'write',
+        completionGeneration: context.generation,
+        currentGeneration: context.generation,
+        completion,
+    });
+}
+function disabledOperation() {
+    const state = {
+        status: 'suppressed',
+        reason: 'provisioning-disabled',
+        detail: 'USB composition provisioning is not configured',
+        current: null,
+        enumerated: [],
+        offerable: [],
+    };
+    const descriptor = descriptorFor(state);
+    return {
+        descriptor,
+        describe: () => Promise.resolve(descriptor),
+        capability: () => Promise.resolve(state),
+        read: (context) => Promise.resolve(result(context, { status: 'applied', value: state })),
+        write: (context) => Promise.resolve(result(context, { status: 'refused', reason: state.reason })),
+    };
+}
+export function createRuntimeCompositionOperation(deps) {
+    if (deps === undefined)
+        return disabledOperation();
+    const capability = async (context) => {
+        const vendor = (await deps.vendor(context)).trim().toLowerCase();
+        if (!isRuntimeCompositionVendor(vendor))
+            return suppressed('unknown-vendor', `No reviewed composition query exists for ${vendor}`);
+        if (!(await deps.provisioningEnabled(context)))
+            return suppressed('provisioning-disabled', 'USB composition provisioning is disabled');
+        const blocked = await deps.blockedReason(context);
+        if (blocked !== undefined)
+            return suppressed('blocked-by-state', blocked);
+        const queries = RUNTIME_COMPOSITION_QUERY_REGISTRY[vendor];
+        const lease = new AtCommandLease({
+            sender: deps.atSender,
+            allowlist: computeAtAllowlist([]),
+        });
+        const current = await lease.run(queries.current);
+        const enumeration = await lease.run(queries.enumerate);
+        const resolved = resolveRuntimeCompositionCapability({
+            vendor,
+            currentResponse: current.raw,
+            enumerationResponse: enumeration.raw,
+        });
+        if (resolved.status === 'unknown')
+            return suppressed('no-return-path', resolved.reason, resolved);
+        if (!resolved.returnPathProven)
+            return suppressed('no-return-path', 'The current mode is absent from the device catalog', resolved);
+        return {
+            status: 'available',
+            current: resolved.current,
+            enumerated: resolved.enumerated,
+            offerable: resolved.offerable.filter((mode) => !Object.is(mode, resolved.current)),
+        };
+    };
+    return {
+        descriptor: descriptorFor(suppressed('provisioning-disabled', 'Capability has not been read for this device')),
+        describe: async (context) => descriptorFor(await capability(context)),
+        capability,
+        read: async (context) => result(context, { status: 'applied', value: await capability(context) }),
+        write: async (context, target) => {
+            const state = await capability(context);
+            if (state.status === 'suppressed')
+                return result(context, { status: 'refused', reason: state.reason });
+            if (!state.offerable.some((candidate) => Object.is(candidate, target)))
+                return result(context, { status: 'refused', reason: 'no-return-path' });
+            const fullCapability = {
+                status: 'available',
+                current: state.current,
+                enumerated: state.enumerated,
+                returnPathProven: true,
+                offerable: [state.current, ...state.offerable],
+            };
+            const outcome = await deps.transition(context, fullCapability, target);
+            if (outcome.status === 'refused')
+                return result(context, { status: 'refused', reason: 'blocked-by-state' });
+            if (outcome.status === 'failed')
+                return result(context, { status: 'failed', reason: outcome.reason });
+            return result(context, {
+                status: 'applied',
+                value: {
+                    status: 'available',
+                    current: target,
+                    enumerated: state.enumerated,
+                    offerable: state.enumerated.filter((mode) => !Object.is(mode, target)),
+                },
+            });
+        },
+    };
+}

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