@ceralive/modem-control 1.2.1 → 1.3.0

package/dist/backend/usb-mode-transition/outcome.js

@@ -0,0 +1,17 @@
+import { readRuntimeCompositionCurrent } from '../../usb-mode/index.js';
+import { descriptorsMatch, detectUsbMode } from '../device-classifier.js';
+export async function transitionPostconditionFailure(plan, device, lease, inhibitUid, steps) {
+    if (plan.proof.tier === 'catalog-descriptors') {
+        const observedMode = detectUsbMode(device);
+        const descriptorsOk = descriptorsMatch(device, plan.proof.transition.expectedDescriptors);
+        return observedMode === plan.proof.transition.to && descriptorsOk
+            ? undefined
+            : `postcondition mismatch: observed ${observedMode ?? 'unknown'} vs target ${plan.proof.transition.to}; descriptors ${descriptorsOk ? 'ok' : 'mismatch'}`;
+    }
+    steps.push('postcondition-runtime-read');
+    const response = await lease.run(plan.proof.currentQuery, { inhibitUid });
+    const observed = readRuntimeCompositionCurrent(plan.proof.vendor, response.raw);
+    return Object.is(observed, plan.proof.target)
+        ? undefined
+        : `runtime readback mismatch: observed ${observed ?? 'unknown'} vs target ${plan.proof.target}`;
+}

package/dist/backend/usb-mode-transition/reenumeration.d.ts

@@ -0,0 +1,8 @@
+import type { UsbDeviceSnapshot } from '../device-classifier.js';
+export declare class ReenumerationWaiter {
+    #private;
+    constructor(enumerate: () => Promise<readonly UsbDeviceSnapshot[]>, timeoutMs: number, pollMs: number);
+    awaitPortDrop(uid: string): Promise<void>;
+    awaitDevice(uid: string): Promise<UsbDeviceSnapshot>;
+    reprobe(): Promise<void>;
+}

package/dist/backend/usb-mode-transition/reenumeration.js

@@ -0,0 +1,37 @@
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class ReenumerationWaiter {
+    #enumerate;
+    #timeoutMs;
+    #pollMs;
+    constructor(enumerate, timeoutMs, pollMs) {
+        this.#enumerate = enumerate;
+        this.#timeoutMs = timeoutMs;
+        this.#pollMs = pollMs;
+    }
+    async awaitPortDrop(uid) {
+        const deadline = Date.now() + this.#timeoutMs;
+        while (Date.now() < deadline) {
+            const devices = await this.#enumerate();
+            if (!devices.some((device) => device.physicalUid === uid)) {
+                return;
+            }
+            await sleep(this.#pollMs);
+        }
+        throw new Error(`control port did not drop within ${this.#timeoutMs}ms (uid ${uid})`);
+    }
+    async awaitDevice(uid) {
+        const deadline = Date.now() + this.#timeoutMs;
+        while (Date.now() < deadline) {
+            const devices = await this.#enumerate();
+            const device = devices.find((candidate) => candidate.physicalUid === uid);
+            if (device !== undefined) {
+                return device;
+            }
+            await sleep(this.#pollMs);
+        }
+        throw new Error(`device did not re-enumerate within ${this.#timeoutMs}ms (uid ${uid})`);
+    }
+    async reprobe() {
+        await this.#enumerate().then(() => undefined, () => undefined);
+    }
+}

package/dist/backend/usb-mode-transition.d.ts

@@ -1,7 +1,7 @@
 import type { DeviceIfname, ModemManagerPort, NetworkManagerPort } from '../ports/index.js';
 import { type CertifiedCatalog } from '../usb-mode/index.js';
-import { type AtAuditSink, type AtCommandSender } from './at-lease.js';
-import { type UsbDeviceSnapshot } from './device-classifier.js';
+import type { AtAuditSink, AtCommandSender } from './at-lease.js';
+import type { UsbDeviceSnapshot } from './device-classifier.js';
 import type { ModemActor } from './modem-actor.js';
 import { type TransitionInterlock, type UsbModeTransitionOutcome, type UsbModeTransitionRequest } from './transition-preconditions.js';
 /** Construction dependencies for the transition. Everything I/O is injectable. */

package/dist/backend/usb-mode-transition.js

@@ -20,11 +20,12 @@
 // reactivate, and still releases the interlock via `finally`. A hung command trips the
 // AT watchdog, which force-uninhibits so the system reprobes rather than wedging.
 import { deviceIfname } from '../ports/index.js';
-import { CERTIFIED_CATALOG, readRuntimeCompositionCurrent, } from '../usb-mode/index.js';
-import { AtCommandLease, computeAtAllowlist, } from './at-lease.js';
-import { descriptorsMatch, detectUsbMode } from './device-classifier.js';
-import { ALLOW_ALL_TRANSITION_INTERLOCK, checkTransitionPreconditions, } from './transition-preconditions.js';
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+import { CERTIFIED_CATALOG } from '../usb-mode/index.js';
+import { ALLOW_ALL_TRANSITION_INTERLOCK, } from './transition-preconditions.js';
+import { checkTransitionAdmission, releaseInhibit } from './usb-mode-transition/admission.js';
+import { createTransitionAtLease } from './usb-mode-transition/at.js';
+import { transitionPostconditionFailure } from './usb-mode-transition/outcome.js';
+import { ReenumerationWaiter } from './usb-mode-transition/reenumeration.js';
 const DEFAULT_WATCHDOG_MS = 30_000;
 const DEFAULT_REENUM_TIMEOUT_MS = 60_000;
 const DEFAULT_POLL_INTERVAL_MS = 250;
@@ -47,6 +48,7 @@ export class UsbModeTransition {
     #watchdogMs;
     #reenumMs;
     #pollMs;
+    #waiter;
     constructor(deps) {
         this.#actor = deps.actor;
         this.#nm = deps.nm;
@@ -60,12 +62,13 @@ export class UsbModeTransition {
         this.#watchdogMs = deps.watchdogMs ?? DEFAULT_WATCHDOG_MS;
         this.#reenumMs = deps.reenumerationTimeoutMs ?? DEFAULT_REENUM_TIMEOUT_MS;
         this.#pollMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.#waiter = new ReenumerationWaiter(this.#enumerate, this.#reenumMs, this.#pollMs);
     }
     /** Run one transition. Preconditions are checked at entry, then again in-actor. */
     async execute(request) {
         const steps = [];
         // ENTRY check — a doomed request NEVER enters the actor (TIER A: zero calls).
-        const entry = await checkTransitionPreconditions(request, this.#catalog, this.#interlock);
+        const entry = await checkTransitionAdmission(request, this.#catalog, this.#interlock);
         if (!entry.ok) {
             return { status: 'refused', stage: 'entry', reason: entry.reason, steps };
         }
@@ -74,7 +77,7 @@ export class UsbModeTransition {
     async #inActor(request, steps) {
         steps.push('actor-enter');
         // IN-ACTOR re-check — catches a race that closed a gate while queued (TIER B).
-        const recheck = await checkTransitionPreconditions(request, this.#catalog, this.#interlock);
+        const recheck = await checkTransitionAdmission(request, this.#catalog, this.#interlock);
         if (!recheck.ok) {
             return { status: 'refused', stage: 'in-actor', reason: recheck.reason, steps };
         }
@@ -91,19 +94,20 @@ export class UsbModeTransition {
         let inhibit;
         let reactivated = false;
         const forceUninhibit = async () => {
-            if (inhibit === undefined) {
-                return;
-            }
             const held = inhibit;
             inhibit = undefined;
-            steps.push('force-uninhibit');
-            await this.#modemManager.uninhibit(held).catch(() => undefined);
+            await releaseInhibit(this.#modemManager, held, steps);
         };
-        const lease = new AtCommandLease({
+        const lease = createTransitionAtLease({
             sender: this.#atSender,
-            allowlist: computeAtAllowlist(allowlistedCommands),
+            allowlistedCommands,
             timeoutMs: this.#watchdogMs,
-            onWatchdog: forceUninhibit,
+            modemManager: this.#modemManager,
+            currentInhibit: () => inhibit,
+            clearInhibit: () => {
+                inhibit = undefined;
+            },
+            steps,
             ...(this.#audit !== undefined ? { audit: this.#audit } : {}),
         });
         steps.push('nm-quiesce');
@@ -119,7 +123,7 @@ export class UsbModeTransition {
                 await lease.run(plan.applyCommand, { inhibitUid: request.inhibitUid });
             }
             steps.push('await-port-drop');
-            await this.#awaitPortDrop(request.cachedPhysicalUid);
+            await this.#waiter.awaitPortDrop(request.cachedPhysicalUid);
             steps.push('uninhibit');
             if (inhibit !== undefined) {
                 const held = inhibit;
@@ -127,34 +131,11 @@ export class UsbModeTransition {
                 await this.#modemManager.uninhibit(held);
             }
             steps.push('await-reenumeration');
-            const device = await this.#awaitReenumeration(request.cachedPhysicalUid);
+            const device = await this.#waiter.awaitDevice(request.cachedPhysicalUid);
             steps.push('postcondition');
-            if (plan.proof.tier === 'catalog-descriptors') {
-                const observedMode = detectUsbMode(device);
-                const descriptorsOk = descriptorsMatch(device, plan.proof.transition.expectedDescriptors);
-                if (observedMode !== plan.proof.transition.to || !descriptorsOk) {
-                    return {
-                        status: 'failed',
-                        degraded: true,
-                        reason: `postcondition mismatch: observed ${observedMode ?? 'unknown'} vs target ${plan.proof.transition.to}; descriptors ${descriptorsOk ? 'ok' : 'mismatch'}`,
-                        steps,
-                    };
-                }
-            }
-            else {
-                steps.push('postcondition-runtime-read');
-                const response = await lease.run(plan.proof.currentQuery, {
-                    inhibitUid: request.inhibitUid,
-                });
-                const observed = readRuntimeCompositionCurrent(plan.proof.vendor, response.raw);
-                if (!Object.is(observed, plan.proof.target)) {
-                    return {
-                        status: 'failed',
-                        degraded: true,
-                        reason: `runtime readback mismatch: observed ${observed ?? 'unknown'} vs target ${plan.proof.target}`,
-                        steps,
-                    };
-                }
+            const postconditionFailure = await transitionPostconditionFailure(plan, device, lease, request.inhibitUid, steps);
+            if (postconditionFailure !== undefined) {
+                return { status: 'failed', degraded: true, reason: postconditionFailure, steps };
             }
             steps.push('resolve-ifname');
             const newIfname = this.#resolveIfname(device);
@@ -168,7 +149,7 @@ export class UsbModeTransition {
         }
         catch (error) {
             await forceUninhibit();
-            await this.#reprobe();
+            await this.#waiter.reprobe();
             return {
                 status: 'failed',
                 degraded: true,
@@ -186,31 +167,4 @@ export class UsbModeTransition {
             }
         }
     }
-    async #awaitPortDrop(uid) {
-        const deadline = Date.now() + this.#reenumMs;
-        while (Date.now() < deadline) {
-            const devices = await this.#enumerate();
-            if (!devices.some((d) => d.physicalUid === uid)) {
-                return;
-            }
-            await sleep(this.#pollMs);
-        }
-        throw new Error(`control port did not drop within ${this.#reenumMs}ms (uid ${uid})`);
-    }
-    async #awaitReenumeration(uid) {
-        const deadline = Date.now() + this.#reenumMs;
-        while (Date.now() < deadline) {
-            const devices = await this.#enumerate();
-            const device = devices.find((d) => d.physicalUid === uid);
-            if (device !== undefined) {
-                return device;
-            }
-            await sleep(this.#pollMs);
-        }
-        throw new Error(`device did not re-enumerate within ${this.#reenumMs}ms (uid ${uid})`);
-    }
-    /** Best-effort state re-read after a crash — the transaction still fails degraded. */
-    async #reprobe() {
-        await this.#enumerate().then(() => undefined, () => undefined);
-    }
 }

package/dist/domain/mm-enums.d.ts

@@ -10,3 +10,40 @@ export declare function decodeEsimStatus(value: number | undefined): 'no-profile
 export declare function decodePacketServiceState(value: number | undefined): 'detached' | 'attached' | undefined;
 export declare function decodeNetworkRejectionError(value: number | undefined): string | undefined;
 export declare function runtimeIdFromPath(path: string): number | undefined;
+/**
+ * The coarse registration context ModemManager's `3gpp-lac-ci` location source reports.
+ *
+ * Every field is kept as the SOURCE'S OWN TEXT. `locationAreaCode` / `cellId` /
+ * `trackingAreaCode` arrive as uppercase hexadecimal and a consumer that parsed them to
+ * a decimal number would render a different identifier than every other tool on the
+ * device shows; `mnc` is two OR three digits and its width is significant, so a numeric
+ * round-trip loses a leading zero that distinguishes two real operators.
+ *
+ * This is COARSE CELL location and is deliberately NOT a GNSS fix: it names a cell, not
+ * a position. It carries no coordinate, so it is outside the GNSS redaction class and
+ * outside `GNSS_SOURCES`, and decoding it enables nothing — `Location.Setup`'s
+ * `signal_location` argument stays false and this decoder never touches a mask.
+ */
+export interface Mm3gppLacCi {
+    readonly mcc: string;
+    readonly mnc: string;
+    readonly locationAreaCode: string;
+    readonly cellId: string;
+    readonly trackingAreaCode: string;
+}
+/**
+ * Decode the `3gpp-lac-ci` location string, or `undefined` when it is not that shape.
+ *
+ * A token count other than five, or an empty MCC/MNC/CI, decodes to nothing rather than
+ * to a partially-populated record: a cell identifier that is wrong is worse than one
+ * that is missing, because only the second is visible as missing.
+ */
+export declare function decode3gppLacCi(value: string | undefined): Mm3gppLacCi | undefined;
+/**
+ * The PLMN id (`Modem3gpp.OperatorCode`'s spelling) for a decoded `3gpp-lac-ci` value.
+ *
+ * MCC and MNC are concatenated with no separator and no padding — MM splits the operator
+ * code back apart at exactly three characters, so this is the inverse of its own
+ * serialization rather than a guess about the MNC's width.
+ */
+export declare function lacCiOperatorCode(decoded: Mm3gppLacCi): string;

package/dist/domain/mm-enums.js

@@ -137,3 +137,37 @@ export function runtimeIdFromPath(path) {
     const value = /\/(\d+)$/.exec(path)?.[1];
     return value === undefined ? undefined : Number.parseInt(value, 10);
 }
+// ModemManager 1.24.2 `libmm-glib/mm-location-3gpp.c` builds this value with
+//   g_strdup_printf ("%.3s,%s,%lX,%lX,%lX", operator_code, operator_code + 3, lac, ci, tac)
+// so it is a STRING of exactly five comma-separated tokens — MCC, MNC, then LAC, CI and
+// TAC in uppercase hex. Its own parser reads exactly `split[0]`..`split[4]`, so a value
+// with a different token count is not a shape this build should guess at.
+const LAC_CI_TOKENS = 5;
+/**
+ * Decode the `3gpp-lac-ci` location string, or `undefined` when it is not that shape.
+ *
+ * A token count other than five, or an empty MCC/MNC/CI, decodes to nothing rather than
+ * to a partially-populated record: a cell identifier that is wrong is worse than one
+ * that is missing, because only the second is visible as missing.
+ */
+export function decode3gppLacCi(value) {
+    if (value === undefined)
+        return undefined;
+    const tokens = value.trim().split(',');
+    if (tokens.length !== LAC_CI_TOKENS)
+        return undefined;
+    const [mcc, mnc, locationAreaCode, cellId, trackingAreaCode] = tokens.map((token) => token.trim());
+    if (mcc === '' || mnc === '' || cellId === '')
+        return undefined;
+    return { mcc, mnc, locationAreaCode, cellId, trackingAreaCode };
+}
+/**
+ * The PLMN id (`Modem3gpp.OperatorCode`'s spelling) for a decoded `3gpp-lac-ci` value.
+ *
+ * MCC and MNC are concatenated with no separator and no padding — MM splits the operator
+ * code back apart at exactly three characters, so this is the inverse of its own
+ * serialization rather than a guess about the MNC's width.
+ */
+export function lacCiOperatorCode(decoded) {
+    return `${decoded.mcc}${decoded.mnc}`;
+}

package/dist/fcc/coverage.d.ts

@@ -6,6 +6,13 @@ export declare const MM_FCC_UNLOCK_VENDOR_SCRIPTS: {
     readonly '2c7c': 'qmicli';
 };
 export type MmFccUnlockVendorScript = keyof typeof MM_FCC_UNLOCK_VENDOR_SCRIPTS;
+/** Provenance for the exact available-tier mapping mirrored below. */
+export declare const MM_FCC_UNLOCK_SOURCE: {
+    readonly version: '1.24.2';
+    readonly commit: 'f2b9ab1ad78d322f32134a444b5b54c6e8160e19';
+    readonly path: 'data/dispatcher-fcc-unlock/meson.build';
+    readonly installedTier: 'fcc-unlock.available.d';
+};
 /** The interpreters those scripts invoke, and the packages that provide them. */
 export declare const MM_FCC_UNLOCK_RUNTIME_PACKAGES: {
     readonly qmicli: 'libqmi-utils';

package/dist/fcc/coverage.js

@@ -24,6 +24,13 @@ export const MM_FCC_UNLOCK_VENDOR_SCRIPTS = {
     '14c3': 'mbimcli',
     '2c7c': 'qmicli',
 };
+/** Provenance for the exact available-tier mapping mirrored below. */
+export const MM_FCC_UNLOCK_SOURCE = {
+    version: '1.24.2',
+    commit: 'f2b9ab1ad78d322f32134a444b5b54c6e8160e19',
+    path: 'data/dispatcher-fcc-unlock/meson.build',
+    installedTier: 'fcc-unlock.available.d',
+};
 /** The interpreters those scripts invoke, and the packages that provide them. */
 export const MM_FCC_UNLOCK_RUNTIME_PACKAGES = {
     qmicli: 'libqmi-utils',

package/dist/hardware/router-parsers.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { parseJsonWith } from '../json-boundary.js';
 import { parseHilinkXmlValue } from './hilink-protocol.js';
 export * from './hilink-protocol.js';
 const SIM_OBJECT_PATH = /^\/org\/freedesktop\/ModemManager1\/SIM\/\d+$/;
@@ -53,40 +54,10 @@ const ufiBodySchema = z.object({
     params: flatRecordSchema.optional(),
 });
 function parseFlatRecord(body) {
-    const parsed = z
-        .string()
-        .transform((value, context) => {
-        try {
-            return JSON.parse(value);
-        }
-        catch (error) {
-            if (!(error instanceof SyntaxError))
-                throw error;
-            context.addIssue({ code: 'custom', message: 'invalid JSON' });
-            return z.NEVER;
-        }
-    })
-        .pipe(flatRecordSchema)
-        .safeParse(body);
-    return parsed.success ? parsed.data : undefined;
+    return parseJsonWith(flatRecordSchema, body);
 }
 function parseUfiBody(body) {
-    const parsed = z
-        .string()
-        .transform((value, context) => {
-        try {
-            return JSON.parse(value);
-        }
-        catch (error) {
-            if (!(error instanceof SyntaxError))
-                throw error;
-            context.addIssue({ code: 'custom', message: 'invalid JSON' });
-            return z.NEVER;
-        }
-    })
-        .pipe(ufiBodySchema)
-        .safeParse(body);
-    return parsed.success ? parsed.data : undefined;
+    return parseJsonWith(ufiBodySchema, body);
 }
 export function parseHilinkSignal(input) {
     const authStatus = parseHilinkXmlValue(input.status, 'code') === '125002';

package/dist/json-boundary.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+type JsonSchema<T> = z.ZodType<T>;
+export declare function parseJsonWith<T>(schema: JsonSchema<T>, body: string): T | undefined;
+export {};

package/dist/json-boundary.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export function parseJsonWith(schema, body) {
+    const parsed = z
+        .string()
+        .transform((value, context) => {
+        try {
+            return JSON.parse(value);
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                throw error;
+            context.addIssue({ code: 'custom', message: 'invalid JSON' });
+            return z.NEVER;
+        }
+    })
+        .pipe(schema)
+        .safeParse(body);
+    return parsed.success ? parsed.data : undefined;
+}

package/dist/observations/model.d.ts

@@ -17,6 +17,50 @@ export type NormalizedRadio = {
     readonly registration: NormalizedMetric<string>;
     readonly accessTechnologies: NormalizedMetric<readonly RadioAccessTechnology[]>;
     readonly modeLabel: NormalizedMetric<string>;
+    /**
+     * The operator the modem is REGISTERED WITH right now — `Modem3gpp.OperatorName`.
+     *
+     * Deliberately NOT `Sim.OperatorName`, which is the HOME operator written into the
+     * SIM. The two agree on a home network and disagree the entire time a device is
+     * roaming, which is exactly when an operator is looking at this field.
+     */
+    readonly operatorName: NormalizedMetric<string>;
+    /**
+     * The registered operator's PLMN id (MCC+MNC) — `Modem3gpp.OperatorCode`.
+     *
+     * Kept as text, not a number: the MNC is two OR three digits and the width is
+     * significant, so `732101` and `73201` are different networks and a numeric
+     * round-trip would lose the leading zero that separates them.
+     */
+    readonly operatorCode: NormalizedMetric<string>;
+};
+/**
+ * Coarse registration context — WHICH CELL, not where the device is.
+ *
+ * This is the `3gpp-lac-ci` location source's output, and it is a different class of
+ * datum from a GNSS fix: it names a cell in the operator's network and carries no
+ * coordinate. That is why it lives here rather than behind the GPS module's privacy
+ * fence, why `3gpp-lac-ci` stays outside `GNSS_SOURCES`, and why nothing on this path
+ * enables a location source or flips `Location.Setup`'s `signal_location`.
+ *
+ * Both fields are the SOURCE'S OWN TEXT. ModemManager emits them as uppercase hex, the
+ * ZTE and UFI admin APIs emit their own vendor spellings, and no radix is common to all
+ * three — so parsing to a number here would render an identifier that matches nothing
+ * an operator sees in `mmcli` or in the vendor's own web UI.
+ *
+ * EARFCN IS ABSENT ON PURPOSE and cannot be added from these sources. ModemManager
+ * publishes no generic ARFCN anywhere on the `Modem`, `Modem3gpp` or `Location`
+ * interfaces (checked against 1.24.2's introspection, not recalled); the only place one
+ * appears is inside a PER-CELL `GetCellInfo` dict, under two DIFFERENT keys — `earfcn`
+ * for LTE (`libmm-glib/mm-cell-info-lte.c`) and `nrarfcn` for 5GNR
+ * (`libmm-glib/mm-cell-info-nr5g.c`). A single normalized slot would therefore have to
+ * either merge two different quantities or silently pick a RAT, so this model makes no
+ * ARFCN claim at all and `backend/cell-info.ts` keeps the per-cell reading where it
+ * belongs.
+ */
+export type NormalizedCell = {
+    readonly cellId: NormalizedMetric<string>;
+    readonly tac: NormalizedMetric<string>;
 };
 /**
  * Signal metrics.
@@ -75,6 +119,7 @@ export type NormalizedModemObservation = {
     readonly radio: NormalizedRadio;
     readonly signal: NormalizedSignal;
     readonly sim: NormalizedSim;
+    readonly cell: NormalizedCell;
     /** Everything the provider said, verbatim, plus what was and was not claimed. */
     readonly diagnostics: ObservationDiagnostics;
 };

package/dist/observations/raw.d.ts

@@ -20,6 +20,18 @@ export declare function hasRawField(record: RawFieldRecord, key: string): boolea
 export declare function rawStructMember(record: RawFieldRecord, key: string, index: number): RawFieldValue | undefined;
 export declare function rawNumberAt(record: RawFieldRecord, key: string, index: number): number | undefined;
 export declare function rawBooleanAt(record: RawFieldRecord, key: string, index: number): boolean | undefined;
+/**
+ * One member of a D-Bus DICT (`a{sv}`) retained verbatim.
+ *
+ * A dict decodes to `[key, value][]`, so a retained `Modem.Signal.Lte` is a nested pair
+ * array rather than a flat scalar. Reading it by member name here — instead of flattening
+ * it at retention time — is what keeps `error-rate` and every future MM key in the
+ * diagnostics block while a metric claims only the member it names.
+ */
+export declare function rawDictMember(record: RawFieldRecord, key: string, member: string): RawFieldValue | undefined;
+/** Whether a retained dict CARRIES a member — absent and undecodable stay separable. */
+export declare function hasRawDictMember(record: RawFieldRecord, key: string, member: string): boolean;
+export declare function rawDictNumber(record: RawFieldRecord, key: string, member: string): number | undefined;
 /**
  * Flatten every leaf element of an XML body into `<body>.<Tag>` entries.
  *

package/dist/observations/raw.js

@@ -77,6 +77,37 @@ export function rawBooleanAt(record, key, index) {
     const member = rawStructMember(record, key, index);
     return typeof member === 'boolean' ? member : undefined;
 }
+/**
+ * One member of a D-Bus DICT (`a{sv}`) retained verbatim.
+ *
+ * A dict decodes to `[key, value][]`, so a retained `Modem.Signal.Lte` is a nested pair
+ * array rather than a flat scalar. Reading it by member name here — instead of flattening
+ * it at retention time — is what keeps `error-rate` and every future MM key in the
+ * diagnostics block while a metric claims only the member it names.
+ */
+export function rawDictMember(record, key, member) {
+    const dict = record[key];
+    if (!Array.isArray(dict))
+        return undefined;
+    for (const entry of dict) {
+        if (Array.isArray(entry) && entry.length >= 2 && entry[0] === member)
+            return entry[1];
+    }
+    return undefined;
+}
+/** Whether a retained dict CARRIES a member — absent and undecodable stay separable. */
+export function hasRawDictMember(record, key, member) {
+    return rawDictMember(record, key, member) !== undefined;
+}
+export function rawDictNumber(record, key, member) {
+    const value = rawDictMember(record, key, member);
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== 'string' || value.trim() === '')
+        return undefined;
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
 const XML_LEAF = /<([A-Za-z_][\w.-]*)>([^<]*)<\/\1>/g;
 /**
  * Flatten every leaf element of an XML body into `<body>.<Tag>` entries.

package/dist/observations/sources/hilink.js

@@ -17,7 +17,7 @@ import { freshObservation, metricProvenance } from '../envelope.js';
 import { knownMetric, metricFromRouterSignal, metricUnknownReasonFromRouter, unknownMetric, } from '../metric.js';
 import { createObservationDiagnostics } from '../provenance.js';
 import { flattenXmlBody, hasRawField, mergeRawRecords, rawKey } from '../raw.js';
-import { routerHardware, routerSim, unsupportedQualityRecent, unsupportedRadioMetric, } from './router-shared.js';
+import { routerCell, routerHardware, routerOperator, routerSim, unsupportedQualityRecent, unsupportedRadioMetric, } from './router-shared.js';
 const SOURCE = 'huawei-hilink';
 const STATUS = 'monitoring-status';
 const SIGNAL = 'device-signal';
@@ -57,6 +57,9 @@ export function normalizeHilinkObservation(input, context) {
             registration: unsupportedRadioMetric(provenance),
             accessTechnologies: unknownMetric('unsupported', provenance([])),
             modeLabel: normalizeModeLabel(capabilities.net_mode, provenance),
+            // The registered operator lives on `/api/net/current-plmn`, a body this
+            // source does not read and no migrated parser decodes.
+            ...routerOperator(provenance, undefined),
         },
         signal: {
             quality: unknownMetric('unsupported', provenance([])),
@@ -70,6 +73,9 @@ export function normalizeHilinkObservation(input, context) {
             sinr: metricFromRouterSignal(signalModel.sinr, provenance([rawKey(SIGNAL, 'sinr')])),
         },
         sim: routerSim(provenance, hasRawField(raw, SIM_STATUS) ? SIM_STATUS : undefined),
+        // HiLink's `<cell_id>` is a raw tag no migrated parser reads; it stays verbatim
+        // in the diagnostics block rather than being lifted into a claim.
+        cell: routerCell(provenance, undefined),
         diagnostics: createObservationDiagnostics({ source: SOURCE, raw, consumed, notes }),
     });
 }

package/dist/observations/sources/modemmanager.d.ts

@@ -14,5 +14,30 @@ export type ModemManagerObservationInput = {
     readonly modem3gpp?: Readonly<Record<string, RawFieldValue>>;
     readonly sim?: Readonly<Record<string, RawFieldValue>>;
     readonly signal?: Readonly<Record<string, RawFieldValue>>;
+    /**
+     * The `Modem.Location` reading, keyed by DECODED SOURCE NAME (`3gpp-lac-ci`).
+     *
+     * On the wire that property is an `a{uv}` keyed by the `MMModemLocationSource` BIT,
+     * and the bit-to-name vocabulary lives in `backend/mm-location.ts`. Naming the
+     * source here instead keeps this layer reading a flat named field like every other
+     * body, and keeps exactly one copy of that vocabulary.
+     *
+     * Supplying it enables nothing. A location SOURCE is switched on by
+     * `Location.Setup`, which this layer never calls; reading a value that is already
+     * being reported is a normalization step. `3gpp-lac-ci` in particular is coarse cell
+     * context rather than a GNSS fix, so it stays outside `GNSS_SOURCES` and the GNSS
+     * enable/disable path is untouched by it.
+     *
+     * NOTHING SUPPLIES IT TODAY, and the reason is the fence rather than an oversight.
+     * ModemManager masks the `Location` PROPERTY unless `Location.Setup` was called with
+     * `signal_location = true` — which broadcasts the value over `PropertiesChanged` and
+     * is therefore permanently forbidden here (`backend/mm-location.ts`). The value has
+     * to come from an explicit `GetLocation()` call instead, and the provider's snapshot
+     * path makes no such call. So an MM observation reads `not-observed` for `cell`:
+     * nobody looked, which is the honest answer and is distinct from a modem that
+     * reported nothing. Cell identity that IS wired today comes from `Modem.GetCellInfo`
+     * through `backend/cell-info.ts`, a different method that needs no location source.
+     */
+    readonly location?: Readonly<Record<string, RawFieldValue>>;
 };
 export declare function normalizeModemManagerObservation(input: ModemManagerObservationInput, context: NormalizationContext): ObservationEnvelope<NormalizedModemObservation>;