@ceralive/modem-control 1.0.0 → 1.2.0

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

@@ -0,0 +1,137 @@
+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';
+import type { RuntimeCompositionOperation } from './runtime-composition-operation.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 usbComposition: RuntimeCompositionOperation;
+    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 {};

package/dist/providers/network-manager/adapter.d.ts

@@ -0,0 +1,71 @@
+import type { DeviceGeneration } from '../../domain/index.js';
+import type { AppliedConfiguration, DesiredProfile, ModemStateView, NormalizationContext, ObservedState, StateDivergence } from '../../observations/index.js';
+import type { ConnectionId, DeviceIfname, GsmProfile, NetworkManagerPort } from '../../ports/index.js';
+import type { NmApplyResult, NmBearerState, NmDesiredRequest, NmObservationInput, NmObservationResult, NmSaveResult } from './types.js';
+export interface NetworkManagerAdapterOptions {
+    readonly port: NetworkManagerPort;
+    /** Clock for the desired/applied slots only; observations carry their own. */
+    readonly now?: () => number;
+}
+export interface NmApplyOptions {
+    readonly operationId: string;
+    readonly generation: DeviceGeneration;
+}
+export declare class NetworkManagerAdapter {
+    #private;
+    constructor(options: NetworkManagerAdapterOptions);
+    /** Every connection this adapter holds a slot for, in insertion order. */
+    trackedConnections(): readonly ConnectionId[];
+    /**
+     * Save an operator's profile and record it as DESIRED.
+     *
+     * The desired slot is built from what the caller ASKED for, not from what NM read
+     * back. That is the whole point of the slot: if NM normalized a field on the way
+     * in, the next `describeStateDivergence` is supposed to report it, and seeding
+     * desired from the readback would make that divergence structurally invisible.
+     */
+    saveDesiredProfile(request: NmDesiredRequest): Promise<NmSaveResult>;
+    /**
+     * Record that the operator wants NO bearer on this connection's device.
+     *
+     * It performs no I/O on purpose — desired is a record of intent, and the
+     * deactivation it implies happens when `applyDesired` is called, so a request and
+     * its execution stay two separately observable facts.
+     */
+    releaseDesired(id: ConnectionId, requestedBy: string): NmSaveResult;
+    desiredFor(id: ConnectionId): DesiredProfile<NmBearerState> | null;
+    /** The saved profile as NM itself holds it — a straight read, no slot involved. */
+    readSavedProfile(id: ConnectionId): Promise<GsmProfile | undefined>;
+    /**
+     * Put the desired state into force and record what was applied.
+     *
+     * The applied slot is built from the profile NM READ BACK, not from the request:
+     * "what was actually put into force" is a claim about NM's content, and asserting
+     * it from the input would make a silently-rejected field look applied.
+     */
+    applyDesired(id: ConnectionId, options: NmApplyOptions): Promise<NmApplyResult>;
+    appliedFor(id: ConnectionId): AppliedConfiguration<NmBearerState> | null;
+    /**
+     * The interface the applied bearer landed on, or `null` when no bearer is in
+     * force. An applied `unbound` state resolves to `null` rather than to its device:
+     * there is a device, but no bearer on it, and returning the name would read as one.
+     */
+    resolveAppliedInterface(id: ConnectionId): DeviceIfname | null;
+    /**
+     * Fold one complete NM readout.
+     *
+     * Never touches the desired slot. Clears the applied slot only when the readout
+     * positively contradicts it, and always says which of the four contradictions it
+     * was.
+     */
+    observe(input: NmObservationInput): NmObservationResult;
+    observedFor(id: ConnectionId): ObservedState<NmBearerState> | null;
+    /**
+     * The three-slot view. `context` supplies the provenance for the "we have not
+     * observed this yet" case — this layer has no clock or epoch counter of its own
+     * for observations, so it cannot manufacture one.
+     */
+    stateView(id: ConnectionId, context: NormalizationContext): ModemStateView<NmBearerState, NmBearerState, NmBearerState> | null;
+    /** `desiredVsApplied` ("did our write happen") and `appliedVsObserved` ("did it stick"). */
+    divergence(id: ConnectionId, context: NormalizationContext): StateDivergence | null;
+}

package/dist/providers/network-manager/adapter.js

@@ -0,0 +1,348 @@
+// The thin NetworkManager adapter: desired profiles, applied bearers, and the
+// interface each one landed on — the saved-vs-applied boundary and nothing else.
+//
+// It is the ONLY bearer/APN authority surface in the package. `ModemManagerPort` has
+// no connect verb by construction (`ports/forbidden-surface.test.ts`), and the
+// ModemManager provider has no bearer operation, so nothing else can put a bearer into
+// force. Correspondingly, this adapter performs no radio, band, SIM or power operation:
+// those belong to the ModemManager provider, and expressing them here would create a
+// second writer for a resource the ownership matrix gives to exactly one.
+//
+// Two rules shape every method below.
+//
+// 1. OBSERVED STATE NEVER WRITES THE DESIRED SLOT. `observe()` may clear the applied
+//    slot and always rewrites the observed one; it does not touch `desired` on any
+//    path. Reality overtaking a write does not un-ask the question the operator asked
+//    — and if it did, a re-enumeration would silently erase the configuration the
+//    controller is supposed to restore.
+// 2. WRITES GO THROUGH THE PORT'S TYPED OPERATIONS, AND ONLY THOSE. The NM half of the
+//    port-tagged op set (`ports/ops.ts` `NmOp`) is create / update / activate /
+//    deactivate. There is deliberately no delete path here: profile removal is not in
+//    that set, so this adapter cannot express it.
+import { epochMillis } from '../../domain/index.js';
+import { appliedConfiguration, describeStateDivergence, desiredProfile, freshObservation, observedState, unavailableObservation, } from '../../observations/index.js';
+import { receipt } from '../../ports/index.js';
+import { boundBearer, nmBearerStateEquals, unboundBearer } from './types.js';
+const SOURCE = 'networkmanager';
+/** The device states in which NM is still settling an activation, not losing it. */
+const TRANSITIONAL_STATES = new Set([
+    'prepare',
+    'config',
+    'need-auth',
+    'ip-config',
+    'ip-check',
+    'secondaries',
+    'deactivating',
+]);
+export class NetworkManagerAdapter {
+    #port;
+    #now;
+    #slots = new Map();
+    #observedGeneration = null;
+    constructor(options) {
+        this.#port = options.port;
+        this.#now = options.now ?? Date.now;
+    }
+    /** Every connection this adapter holds a slot for, in insertion order. */
+    trackedConnections() {
+        return [...this.#slots.keys()];
+    }
+    // ── desired ────────────────────────────────────────────────────────────────
+    /**
+     * Save an operator's profile and record it as DESIRED.
+     *
+     * The desired slot is built from what the caller ASKED for, not from what NM read
+     * back. That is the whole point of the slot: if NM normalized a field on the way
+     * in, the next `describeStateDivergence` is supposed to report it, and seeding
+     * desired from the readback would make that divergence structurally invisible.
+     */
+    async saveDesiredProfile(request) {
+        let saved;
+        try {
+            saved =
+                request.connectionId === undefined
+                    ? await this.#port.createGsmProfile(request.profile)
+                    : await this.#port.updateGsmProfile(request.connectionId, request.profile);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: 'write-failed',
+                receipt: receipt('connection', 'failed', describeError(error)),
+            };
+        }
+        const id = saved.connectionId;
+        const desired = desiredProfile(boundBearer({
+            connectionId: id,
+            deviceIfname: request.deviceIfname,
+            apn: request.profile.apn,
+            autoConfig: request.profile.autoConfig,
+            homeOnly: request.profile.homeOnly,
+        }), epochMillis(this.#now()), request.requestedBy);
+        this.#slotsFor(id).desired = desired;
+        return { ok: true, connectionId: id, desired };
+    }
+    /**
+     * Record that the operator wants NO bearer on this connection's device.
+     *
+     * It performs no I/O on purpose — desired is a record of intent, and the
+     * deactivation it implies happens when `applyDesired` is called, so a request and
+     * its execution stay two separately observable facts.
+     */
+    releaseDesired(id, requestedBy) {
+        const slots = this.#slots.get(id);
+        const ifname = slots === undefined ? undefined : targetIfname(slots);
+        if (ifname === undefined) {
+            return {
+                ok: false,
+                reason: 'no-desired-profile',
+                receipt: receipt('connection', 'failed', `no tracked device for connection ${id}`),
+            };
+        }
+        const desired = desiredProfile(unboundBearer(ifname), epochMillis(this.#now()), requestedBy);
+        this.#slotsFor(id).desired = desired;
+        return { ok: true, connectionId: id, desired };
+    }
+    desiredFor(id) {
+        return this.#slots.get(id)?.desired ?? null;
+    }
+    /** The saved profile as NM itself holds it — a straight read, no slot involved. */
+    async readSavedProfile(id) {
+        return await this.#port.readGsmProfile(id);
+    }
+    // ── applied ────────────────────────────────────────────────────────────────
+    /**
+     * Put the desired state into force and record what was applied.
+     *
+     * The applied slot is built from the profile NM READ BACK, not from the request:
+     * "what was actually put into force" is a claim about NM's content, and asserting
+     * it from the input would make a silently-rejected field look applied.
+     */
+    async applyDesired(id, options) {
+        const desired = this.desiredFor(id);
+        if (desired === null) {
+            return refuse('no-desired-profile', `connection ${id} has no desired profile`);
+        }
+        return desired.profile.kind === 'unbound'
+            ? await this.#deactivate(id, desired.profile.deviceIfname, options)
+            : await this.#activate(id, desired.profile, options);
+    }
+    appliedFor(id) {
+        return this.#slots.get(id)?.applied ?? null;
+    }
+    /**
+     * The interface the applied bearer landed on, or `null` when no bearer is in
+     * force. An applied `unbound` state resolves to `null` rather than to its device:
+     * there is a device, but no bearer on it, and returning the name would read as one.
+     */
+    resolveAppliedInterface(id) {
+        const applied = this.appliedFor(id);
+        if (applied === null || applied.configuration.kind !== 'bound') {
+            return null;
+        }
+        return applied.configuration.binding.deviceIfname;
+    }
+    // ── observed ───────────────────────────────────────────────────────────────
+    /**
+     * Fold one complete NM readout.
+     *
+     * Never touches the desired slot. Clears the applied slot only when the readout
+     * positively contradicts it, and always says which of the four contradictions it
+     * was.
+     */
+    observe(input) {
+        const generation = input.context.generation;
+        if (this.#observedGeneration !== null && generation < this.#observedGeneration) {
+            return {
+                kind: 'refused',
+                reason: 'superseded-generation',
+                currentGeneration: this.#observedGeneration,
+            };
+        }
+        this.#observedGeneration = generation;
+        const devices = new Map(input.devices.map((device) => [device.ifname, device]));
+        const outcomes = [];
+        const losses = [];
+        for (const [id, slots] of this.#slots) {
+            const ifname = targetIfname(slots);
+            if (ifname === undefined) {
+                continue;
+            }
+            const device = devices.get(ifname);
+            slots.observed = observedState(device === undefined
+                ? unavailableObservation(SOURCE, input.context, 'device-absent')
+                : freshObservation(SOURCE, input.context, observedBearer(device)));
+            const outcome = this.#classify(id, slots, ifname, device, input.context.observedAt);
+            outcomes.push({ connectionId: id, outcome });
+            if (outcome.status === 'lost') {
+                losses.push(outcome.loss);
+            }
+        }
+        return {
+            kind: 'accepted',
+            generation,
+            observedAt: input.context.observedAt,
+            outcomes,
+            losses,
+        };
+    }
+    observedFor(id) {
+        return this.#slots.get(id)?.observed ?? null;
+    }
+    /**
+     * The three-slot view. `context` supplies the provenance for the "we have not
+     * observed this yet" case — this layer has no clock or epoch counter of its own
+     * for observations, so it cannot manufacture one.
+     */
+    stateView(id, context) {
+        const slots = this.#slots.get(id);
+        if (slots === undefined) {
+            return null;
+        }
+        return {
+            desired: slots.desired,
+            applied: slots.applied,
+            observed: slots.observed ??
+                observedState(unavailableObservation(SOURCE, context, 'provider-unavailable')),
+        };
+    }
+    /** `desiredVsApplied` ("did our write happen") and `appliedVsObserved` ("did it stick"). */
+    divergence(id, context) {
+        const view = this.stateView(id, context);
+        return view === null ? null : describeStateDivergence(view, nmBearerStateEquals);
+    }
+    // ── internals ──────────────────────────────────────────────────────────────
+    async #activate(id, desired, options) {
+        if (desired.kind !== 'bound') {
+            return refuse('no-desired-profile', `connection ${id} has no bearer to activate`);
+        }
+        const ifname = desired.binding.deviceIfname;
+        const saved = await this.#port.readGsmProfile(id);
+        if (saved === undefined) {
+            return refuse('profile-absent', `connection ${id} is no longer saved in NetworkManager`);
+        }
+        let activation;
+        try {
+            activation = await this.#port.activate(id, ifname);
+        }
+        catch (error) {
+            return refuse('activation-failed', describeError(error));
+        }
+        if (activation.status !== 'applied') {
+            return { ok: false, reason: 'activation-failed', receipt: activation };
+        }
+        const applied = appliedConfiguration({
+            configuration: boundBearer({
+                connectionId: id,
+                deviceIfname: ifname,
+                apn: saved.apn,
+                autoConfig: saved.autoConfig,
+                homeOnly: saved.homeOnly,
+            }),
+            appliedAt: epochMillis(this.#now()),
+            generation: options.generation,
+            operationId: options.operationId,
+        });
+        this.#slotsFor(id).applied = applied;
+        return { ok: true, applied, receipt: activation };
+    }
+    async #deactivate(id, ifname, options) {
+        let result;
+        try {
+            result = await this.#port.deactivate(id, ifname);
+        }
+        catch (error) {
+            return refuse('deactivation-failed', describeError(error));
+        }
+        if (result.status !== 'applied') {
+            return { ok: false, reason: 'deactivation-failed', receipt: result };
+        }
+        const applied = appliedConfiguration({
+            configuration: unboundBearer(ifname),
+            appliedAt: epochMillis(this.#now()),
+            generation: options.generation,
+            operationId: options.operationId,
+        });
+        this.#slotsFor(id).applied = applied;
+        return { ok: true, applied, receipt: result };
+    }
+    #classify(id, slots, ifname, device, observedAt) {
+        const applied = slots.applied;
+        if (applied === null) {
+            return { status: 'unapplied' };
+        }
+        const lose = (reason) => {
+            slots.applied = null;
+            return {
+                status: 'lost',
+                loss: {
+                    connectionId: id,
+                    deviceIfname: ifname,
+                    reason,
+                    lostAt: observedAt,
+                    generation: applied.generation,
+                    previous: applied,
+                },
+            };
+        };
+        if (device === undefined) {
+            return lose('interface-absent');
+        }
+        if (device.state === 'failed') {
+            return lose('activation-failed');
+        }
+        if (applied.configuration.kind === 'unbound') {
+            // We deliberately took the bearer down; anything active here is somebody else.
+            return device.activeConnection === undefined
+                ? { status: 'retained', applied }
+                : lose('connection-replaced');
+        }
+        if (device.activeConnection === undefined) {
+            return lose('interface-detached');
+        }
+        if (device.activeConnection.connectionId !== id) {
+            return lose('connection-replaced');
+        }
+        if (device.state === 'activated') {
+            return { status: 'retained', applied };
+        }
+        return TRANSITIONAL_STATES.has(device.state)
+            ? { status: 'pending', applied, deviceState: device.state }
+            : lose('interface-detached');
+    }
+    #slotsFor(id) {
+        const existing = this.#slots.get(id);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const created = { desired: null, applied: null, observed: null };
+        this.#slots.set(id, created);
+        return created;
+    }
+}
+/** The device the slots are about: where the bearer IS, else where it was asked for. */
+function targetIfname(slots) {
+    const state = slots.applied?.configuration ?? slots.desired?.profile;
+    if (state === undefined) {
+        return undefined;
+    }
+    return state.kind === 'bound' ? state.binding.deviceIfname : state.deviceIfname;
+}
+function observedBearer(device) {
+    const active = device.activeConnection;
+    return active === undefined
+        ? unboundBearer(device.ifname)
+        : boundBearer({
+            connectionId: active.connectionId,
+            deviceIfname: device.ifname,
+            apn: active.apn,
+            autoConfig: active.autoConfig,
+            homeOnly: active.homeOnly,
+        });
+}
+function refuse(reason, message) {
+    return { ok: false, reason, receipt: receipt('connection', 'failed', message) };
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : 'NetworkManager rejected the request';
+}

package/dist/providers/network-manager/index.d.ts

@@ -0,0 +1,2 @@
+export * from './adapter.js';
+export * from './types.js';

package/dist/providers/network-manager/index.js

@@ -0,0 +1,2 @@
+export * from './adapter.js';
+export * from './types.js';