@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/providers/matcher.js

@@ -0,0 +1,205 @@
+const STRENGTH_POINTS = {
+    none: 0,
+    weak: 1,
+    moderate: 2,
+    strong: 3,
+};
+function scoreOf(points) {
+    if (points <= 0)
+        return 'unsupported';
+    if (points === 1)
+        return 'maybe';
+    if (points === 2)
+        return 'likely';
+    return 'supported';
+}
+function confidenceOf(points) {
+    return Math.min(1, points / 3);
+}
+function cacheSignature(request, registryRevision) {
+    return JSON.stringify({
+        registryRevision,
+        generation: request.generation,
+        transport: request.transport,
+        passiveFacts: request.passiveFacts,
+        composition: request.composition,
+        firmware: request.firmware ?? null,
+    });
+}
+function addCandidate(candidates, provider, profile, strength) {
+    const key = `${provider.id}\u0000${profile}`;
+    const existing = candidates.get(key);
+    if (existing === undefined) {
+        candidates.set(key, { provider, profile, points: STRENGTH_POINTS[strength] });
+        return;
+    }
+    existing.points += STRENGTH_POINTS[strength];
+}
+function unresolvedResult(status, request, points, evidence, conflicts) {
+    return {
+        status,
+        provider: null,
+        profile: null,
+        score: scoreOf(points),
+        confidence: confidenceOf(points),
+        evidence,
+        conflicts,
+        operations: null,
+        writable: false,
+        generation: request.generation,
+        physicalModemId: request.physicalModemId,
+    };
+}
+async function evaluate(registry, request) {
+    const evidence = [];
+    const conflicts = [];
+    const candidates = new Map();
+    const eligible = [];
+    for (const provider of registry.list()) {
+        const transportMatches = provider.eligibleTransports.includes(request.transport);
+        evidence.push({
+            provider: provider.id,
+            profile: null,
+            stage: 'transport-eligibility',
+            source: request.transport,
+            signal: transportMatches ? 'match' : 'mismatch',
+            strength: 'none',
+            detail: transportMatches ? 'eligible-transport' : 'ineligible-transport',
+        });
+        if (transportMatches)
+            eligible.push(provider);
+    }
+    for (const provider of eligible) {
+        for (const matcher of provider.passiveMatchers) {
+            const actual = request.passiveFacts
+                .filter((fact) => fact.kind === matcher.fact)
+                .map((fact) => fact.value);
+            const signal = actual.length === 0
+                ? 'unknown'
+                : actual.some((value) => matcher.expected.includes(value))
+                    ? 'match'
+                    : 'mismatch';
+            const item = {
+                provider: provider.id,
+                profile: matcher.profiles.length === 1 ? (matcher.profiles[0] ?? null) : null,
+                stage: 'passive-facts',
+                source: matcher.id,
+                signal,
+                strength: matcher.strength,
+                detail: signal === 'match' ? 'expected-fact-present' : 'expected-fact-not-proven',
+            };
+            evidence.push(item);
+            if (signal === 'mismatch' && matcher.required)
+                conflicts.push(item);
+            if (signal === 'match') {
+                for (const profile of matcher.profiles) {
+                    addCandidate(candidates, provider, profile, matcher.strength);
+                }
+            }
+        }
+    }
+    for (const provider of eligible) {
+        for (const probe of provider.unauthenticatedProbes) {
+            const result = await probe.run(request);
+            const item = {
+                provider: provider.id,
+                profile: result.profiles.length === 1 ? (result.profiles[0] ?? null) : null,
+                stage: 'unauthenticated-fingerprint',
+                source: probe.id,
+                signal: result.signal,
+                strength: result.strength,
+                detail: result.detail,
+            };
+            evidence.push(item);
+            if (result.signal === 'mismatch')
+                conflicts.push(item);
+            if (result.signal === 'match') {
+                for (const profile of result.profiles) {
+                    addCandidate(candidates, provider, profile, result.strength);
+                }
+            }
+        }
+    }
+    const ranked = [...candidates.values()].sort((left, right) => right.points - left.points);
+    const top = ranked[0];
+    if (top === undefined)
+        return unresolvedResult('unsupported', request, 0, evidence, conflicts);
+    if (ranked[1]?.points === top.points) {
+        return unresolvedResult('ambiguous', request, top.points, evidence, conflicts);
+    }
+    if (top.provider.authenticatedProfile !== undefined) {
+        const auth = await top.provider.authenticatedProfile.authenticate(request, [top.profile]);
+        const matched = auth.status === 'matched' && auth.profile === top.profile;
+        const item = {
+            provider: top.provider.id,
+            profile: top.profile,
+            stage: 'authenticated-profile',
+            source: top.provider.authenticatedProfile.algorithm,
+            signal: matched ? 'match' : auth.status === 'unavailable' ? 'unknown' : 'mismatch',
+            strength: 'strong',
+            detail: auth.detail,
+        };
+        evidence.push(item);
+        if (!matched) {
+            conflicts.push(item);
+            return unresolvedResult('ambiguous', request, top.points, evidence, conflicts);
+        }
+        top.points += STRENGTH_POINTS.strong;
+    }
+    const context = { ...request, profile: top.profile };
+    for (const reader of top.provider.capabilityReaders) {
+        const result = await reader.read(context);
+        const item = {
+            provider: top.provider.id,
+            profile: top.profile,
+            stage: 'capability-read',
+            source: reader.id,
+            signal: result.signal,
+            strength: result.strength,
+            detail: result.detail,
+        };
+        evidence.push(item);
+        if (result.signal === 'match')
+            top.points += STRENGTH_POINTS[result.strength];
+        if (result.signal === 'mismatch')
+            conflicts.push(item);
+    }
+    if (scoreOf(top.points) !== 'supported') {
+        return unresolvedResult('ambiguous', request, top.points, evidence, conflicts);
+    }
+    const operations = top.provider.operations(top.profile);
+    return {
+        status: 'selected',
+        provider: top.provider.id,
+        profile: top.profile,
+        score: 'supported',
+        confidence: confidenceOf(top.points),
+        evidence,
+        conflicts,
+        operations,
+        writable: operations.access === 'read-write',
+        generation: request.generation,
+        physicalModemId: request.physicalModemId,
+    };
+}
+class GenerationScopedProviderMatcher {
+    registry;
+    /** Cache mutation is scoped by physical modem, generation, firmware and composition. */
+    #cache = new Map();
+    constructor(registry) {
+        this.registry = registry;
+    }
+    async match(request) {
+        const key = request.physicalModemId;
+        const signature = cacheSignature(request, this.registry.revision);
+        const cached = this.#cache.get(key);
+        if (cached?.signature === signature)
+            return cached.result;
+        const result = await evaluate(this.registry, request);
+        this.#cache.set(key, { signature, result });
+        return result;
+    }
+}
+export function createProviderMatcher(registry) {
+    return new GenerationScopedProviderMatcher(registry);
+}

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

@@ -0,0 +1,7 @@
+export declare const MODEM_MANAGER_REFUSAL_REASONS: readonly ['unauthorized', 'unsupported', 'wrong-state', 'busy', 'not-found', 'timed-out', 'disconnected', 'failed'];
+export type ModemManagerRefusalReason = (typeof MODEM_MANAGER_REFUSAL_REASONS)[number];
+export type ModemManagerRefusal = {
+    readonly reason: ModemManagerRefusalReason;
+    readonly retryable: boolean;
+};
+export declare function mapModemManagerError(error: unknown): ModemManagerRefusal;

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

@@ -0,0 +1,37 @@
+import { DisconnectedError, TransportError } from '../../transport/index.js';
+export const MODEM_MANAGER_REFUSAL_REASONS = [
+    'unauthorized',
+    'unsupported',
+    'wrong-state',
+    'busy',
+    'not-found',
+    'timed-out',
+    'disconnected',
+    'failed',
+];
+function errorIdentity(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const dbusName = Reflect.get(error, 'dbusName');
+    return `${typeof dbusName === 'string' ? dbusName : error.name} ${error.message}`;
+}
+export function mapModemManagerError(error) {
+    if (error instanceof DisconnectedError)
+        return { reason: 'disconnected', retryable: true };
+    const identity = errorIdentity(error);
+    if (/Unauthorized|AccessDenied/i.test(identity))
+        return { reason: 'unauthorized', retryable: false };
+    if (/Unsupported|NotSupported/i.test(identity))
+        return { reason: 'unsupported', retryable: false };
+    if (/WrongState|InvalidState/i.test(identity))
+        return { reason: 'wrong-state', retryable: true };
+    if (/InProgress|Busy/i.test(identity))
+        return { reason: 'busy', retryable: true };
+    if (/NotFound|UnknownObject|UnknownModem/i.test(identity)) {
+        return { reason: 'not-found', retryable: false };
+    }
+    if (error instanceof TransportError && /timed out/i.test(error.message)) {
+        return { reason: 'timed-out', retryable: true };
+    }
+    return { reason: 'failed', retryable: false };
+}

package/dist/providers/modem-manager/generic-operations.d.ts

@@ -0,0 +1,10 @@
+import type { MmDbusBackend } from '../../backend/index.js';
+import type { ProviderExecutionContext } from '../contracts.js';
+import { type RuntimeCompositionOperationDeps } from './runtime-composition-operation.js';
+import type { ModemManagerProviderOperations, ModemManagerSnapshotResult } from './types.js';
+export interface GenericOperationsDeps {
+    readonly backend: MmDbusBackend;
+    readonly runtimeComposition?: RuntimeCompositionOperationDeps;
+    readSnapshot(context: ProviderExecutionContext): Promise<ModemManagerSnapshotResult>;
+}
+export declare function createGenericOperations(deps: GenericOperationsDeps): Pick<ModemManagerProviderOperations, 'radio' | 'modes' | 'bands' | 'signal' | 'sim' | 'power' | 'usbComposition'>;

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

@@ -0,0 +1,209 @@
+import { classifyOperationCompletion, defineOperationDescriptor, runtimePath, } from '../../domain/index.js';
+import { bandWriteReadbackMatches, buildBandWriteDescriptor, buildModeWriteDescriptor, encodeModeSelection, matchAdvertisedCombination, sameSelection, selectionOf, } from '../../radio/index.js';
+import { mapModemManagerError } from './errors.js';
+import { createRuntimeCompositionOperation, } from './runtime-composition-operation.js';
+const PROVIDER_ID = 'modemmanager';
+const PROFILE = 'generic-mm';
+function readDescriptor(id) {
+    return defineOperationDescriptor({
+        id,
+        support: { read: { supported: true }, write: { supported: false, reason: 'read-only' } },
+        authority: 'provider',
+        provider: PROVIDER_ID,
+        constraints: { kind: 'unconstrained' },
+        livePreconditions: ['modem-present', 'runtime-interface-present'],
+        availability: { state: 'available' },
+        mutationImpact: 'read',
+        retryClass: 'idempotent-read',
+        readback: { required: false },
+        rollback: { required: false },
+        journal: { required: false },
+        admission: { required: false },
+        evidence: { profiles: [PROFILE], firmware: [] },
+        confidence: 'high',
+    });
+}
+function writeDescriptor(id) {
+    return defineOperationDescriptor({
+        id,
+        support: { read: { supported: true }, write: { supported: true } },
+        authority: 'provider',
+        provider: PROVIDER_ID,
+        constraints: { kind: 'unconstrained' },
+        livePreconditions: ['modem-present', 'runtime-interface-present'],
+        availability: { state: 'available' },
+        mutationImpact: 'disruptive',
+        retryClass: 'never',
+        readback: { required: false },
+        rollback: { required: false },
+        journal: { required: true, reason: 'disruptive-radio-write' },
+        admission: { required: true, reason: 'provider-mutation' },
+        evidence: { profiles: [PROFILE], firmware: [] },
+        confidence: 'high',
+    });
+}
+function applied(context, value) {
+    return classifyOperationCompletion({
+        operation: 'read',
+        completionGeneration: context.generation,
+        currentGeneration: context.generation,
+        completion: { status: 'applied', value },
+    });
+}
+function refused(context, reason) {
+    return classifyOperationCompletion({
+        operation: 'read',
+        completionGeneration: context.generation,
+        currentGeneration: context.generation,
+        completion: { status: 'refused', reason },
+    });
+}
+function receiptReason(reason) {
+    const mapped = mapModemManagerError(new Error(reason));
+    return mapped.reason === 'failed' ? reason : mapped.reason;
+}
+export function createGenericOperations(deps) {
+    const readField = async (context, capability, select, reason) => {
+        const snapshot = await deps.readSnapshot(context);
+        if (!snapshot.ok)
+            return refused(context, snapshot.reason);
+        return snapshot.capabilities[capability]
+            ? applied(context, select(snapshot))
+            : refused(context, reason);
+    };
+    const readBands = async (context) => {
+        const snapshot = await deps.readSnapshot(context);
+        if (!snapshot.ok)
+            return refused(context, snapshot.reason);
+        if (!snapshot.capabilities.bandRead)
+            return refused(context, 'band-read-unsupported');
+        const result = await deps.backend.readBands(runtimePath(snapshot.modemPath));
+        return result.ok
+            ? applied(context, result.bands)
+            : refused(context, receiptReason(result.reason));
+    };
+    const radioDescriptor = writeDescriptor('modemmanager.radio-modes');
+    const radio = {
+        descriptor: radioDescriptor,
+        describe: () => Promise.resolve(radioDescriptor),
+        read: (context) => readField(context, 'modeRead', (snapshot) => snapshot.radio, 'mode-read-unsupported'),
+        write: async (context, input) => {
+            const snapshot = await deps.readSnapshot(context);
+            if (!snapshot.ok)
+                return refused(context, snapshot.reason);
+            if (!snapshot.capabilities.modeWrite)
+                return refused(context, 'mode-write-unsupported');
+            const receipt = await deps.backend.setRadioModes(runtimePath(snapshot.modemPath), input);
+            if (receipt.status !== 'applied')
+                return refused(context, receiptReason(receipt.reason));
+            return readField(context, 'modeRead', (next) => next.radio, 'mode-read-unsupported');
+        },
+    };
+    const readModeTruth = async (context) => readField(context, 'modeRead', (snapshot) => snapshot.radio.truth, 'mode-read-unsupported');
+    const modes = {
+        descriptor: buildModeWriteDescriptor({
+            provider: PROVIDER_ID,
+            profile: PROFILE,
+            truth: {
+                current: { state: 'not-reported' },
+                supported: { combinations: [], undecodable: [] },
+            },
+            writeSupported: true,
+        }),
+        describe: async (context) => {
+            const snapshot = await deps.readSnapshot(context);
+            return buildModeWriteDescriptor({
+                provider: PROVIDER_ID,
+                profile: PROFILE,
+                truth: snapshot.ok
+                    ? snapshot.radio.truth
+                    : {
+                        current: { state: 'not-reported' },
+                        supported: { combinations: [], undecodable: [] },
+                    },
+                writeSupported: snapshot.ok && snapshot.capabilities.modeWrite,
+            });
+        },
+        read: readModeTruth,
+        write: async (context, selection) => {
+            const snapshot = await deps.readSnapshot(context);
+            if (!snapshot.ok)
+                return refused(context, snapshot.reason);
+            if (!snapshot.capabilities.modeWrite)
+                return refused(context, 'mode-write-unsupported');
+            // A selection the modem never advertised is refused outright — never rounded to
+            // the nearest advertised one. Substituting is how "prefer 4G" on a marginal cell
+            // silently becomes 5G-first, which `five-g-preference.ts` refuses for the same reason.
+            if (matchAdvertisedCombination(snapshot.radio.truth.supported, selection) === undefined) {
+                return refused(context, 'mode-combination-not-advertised');
+            }
+            const encoded = encodeModeSelection(selection);
+            if (!encoded.ok)
+                return refused(context, 'mode-name-unknown');
+            const receipt = await deps.backend.setModeCombination(runtimePath(snapshot.modemPath), encoded.allowedMask, encoded.preferredMask);
+            if (receipt.status !== 'applied')
+                return refused(context, receiptReason(receipt.reason));
+            const readback = await readModeTruth(context);
+            if (readback.status !== 'applied')
+                return readback;
+            // An accepted-but-ignored `SetCurrentModes` is indistinguishable from success at
+            // the call site, so the descriptor requires a readback and this enforces it.
+            return readback.value.current.state === 'reported' &&
+                sameSelection(selectionOf(readback.value.current.combination), selection)
+                ? readback
+                : refused(context, 'mode-write-readback-mismatch');
+        },
+    };
+    const bandDescriptorFor = (snapshot) => buildBandWriteDescriptor({
+        provider: PROVIDER_ID,
+        profile: PROFILE,
+        certification: snapshot.ok
+            ? snapshot.bandCertification
+            : {
+                required: true,
+                satisfied: false,
+                reason: 'band-certification-required',
+                offerable: [],
+            },
+        readSupported: snapshot.ok && snapshot.capabilities.bandRead,
+    });
+    const bands = {
+        descriptor: bandDescriptorFor({ ok: false, reason: 'not-found' }),
+        describe: async (context) => bandDescriptorFor(await deps.readSnapshot(context)),
+        read: readBands,
+        write: async (context, input) => {
+            const snapshot = await deps.readSnapshot(context);
+            if (!snapshot.ok)
+                return refused(context, snapshot.reason);
+            // The certification gate, second of two. `bandWrite` is already false without a
+            // catalog entry, and the descriptor already reads `refused` — but a band lock can
+            // take a working uplink off the air, so the call path refuses independently
+            // rather than trusting a consumer to have read the descriptor.
+            if (!snapshot.bandCertification.satisfied || !snapshot.capabilities.bandWrite)
+                return refused(context, 'band-write-certification-required');
+            const receipt = await deps.backend.setCurrentBands(runtimePath(snapshot.modemPath), input);
+            if (receipt.status !== 'applied')
+                return refused(context, receiptReason(receipt.reason));
+            const readback = await readBands(context);
+            if (readback.status !== 'applied')
+                return readback;
+            return bandWriteReadbackMatches(input, readback.value)
+                ? readback
+                : refused(context, 'band-write-readback-mismatch');
+        },
+    };
+    const signal = {
+        descriptor: readDescriptor('modemmanager.signal'),
+        read: (context) => readField(context, 'signalRead', (snapshot) => snapshot.signal, 'signal-read-unsupported'),
+    };
+    const sim = {
+        descriptor: readDescriptor('modemmanager.sim'),
+        read: (context) => readField(context, 'simRead', (snapshot) => snapshot.sim, 'sim-read-unsupported'),
+    };
+    const power = {
+        descriptor: readDescriptor('modemmanager.power'),
+        read: (context) => readField(context, 'powerRead', (snapshot) => snapshot.power, 'power-read-unsupported'),
+    };
+    const usbComposition = createRuntimeCompositionOperation(deps.runtimeComposition);
+    return { radio, modes, bands, signal, sim, power, usbComposition };
+}

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

@@ -0,0 +1,4 @@
+export * from './errors.js';
+export * from './provider.js';
+export * from './runtime-composition-operation.js';
+export * from './types.js';

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

@@ -0,0 +1,4 @@
+export * from './errors.js';
+export * from './provider.js';
+export * from './runtime-composition-operation.js';
+export * from './types.js';

package/dist/providers/modem-manager/module-operations.d.ts

@@ -0,0 +1,21 @@
+import type { MmLocation } from '../../backend/index.js';
+import type { DbusTransport } from '../../transport/index.js';
+import type { MmUssd } from '../../ussd/index.js';
+import type { ProviderExecutionContext } from '../contracts.js';
+import type { ModemManagerProviderOperations, ModemManagerSnapshotResult } from './types.js';
+export interface ModuleOperationsOptions {
+    readonly transport: DbusTransport;
+    readonly destination: string;
+    readonly location: MmLocation;
+    readonly ussd: MmUssd;
+    readonly now: () => number;
+    readSnapshot(context: ProviderExecutionContext): Promise<ModemManagerSnapshotResult>;
+}
+type ModuleOperationSurface = Pick<ModemManagerProviderOperations, 'location' | 'sms' | 'ussd' | 'initiateUssd' | 'respondUssd' | 'cancelUssd' | 'fccCoverage'>;
+export declare class ModemManagerModuleOperations {
+    #private;
+    readonly operations: ModuleOperationSurface;
+    constructor(options: ModuleOperationsOptions);
+    stop(): Promise<void>;
+}
+export {};

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,41 @@
+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 { RuntimeCompositionOperationDeps } from './runtime-composition-operation.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;
+    readonly runtimeComposition?: RuntimeCompositionOperationDeps;
+}
+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;