@ceralive/modem-control 1.0.0 → 1.1.0

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

@@ -0,0 +1,18 @@
+import { type ObservationEnvelope } from '../../domain/index.js';
+import { type NormalizationContext } from '../envelope.js';
+import type { NormalizedModemObservation } from '../model.js';
+import { type RawFieldValue } from '../provenance.js';
+/**
+ * The decoded ModemManager property records, one per D-Bus interface.
+ *
+ * A body left out is a body nobody read, and reads as `not-observed` rather than as a
+ * modem that reports nothing — that difference decides whether a consumer retries or
+ * hides a control.
+ */
+export type ModemManagerObservationInput = {
+    readonly modem?: Readonly<Record<string, RawFieldValue>>;
+    readonly modem3gpp?: Readonly<Record<string, RawFieldValue>>;
+    readonly sim?: Readonly<Record<string, RawFieldValue>>;
+    readonly signal?: Readonly<Record<string, RawFieldValue>>;
+};
+export declare function normalizeModemManagerObservation(input: ModemManagerObservationInput, context: NormalizationContext): ObservationEnvelope<NormalizedModemObservation>;

package/dist/observations/sources/modemmanager.js

@@ -0,0 +1,239 @@
+// ModemManager → normalized observation.
+//
+// Every decode here is the MIGRATED logic (`domain/mm-enums.ts`,
+// `domain/modem-presentation.ts`, `hardware/router-parsers.ts` for SIM presence) —
+// this module adds provenance and reason-carrying unknowns, and decodes nothing
+// itself. Where a decoder answers `'unknown'` or `undefined`, the distinction it
+// cannot make is made here from the RAW record: a field that was never in the payload
+// is `not-reported`, an interface nobody read is `not-observed`, and a field that WAS
+// present but decoded to nothing is `malformed` with a diagnostic note. Collapsing
+// those three into one absent value is precisely the loss this layer exists to stop.
+import { decodeEsimStatus, decodeMmAccessTechnologies, decodeMmState, decodeRegistrationState, decodeSimType, decodeStateFailedReason, decodeUnlockRequired, modeMaskToLabel, modemHardwareLabel, modemHardwareName, } from '../../domain/index.js';
+import { readSimPresence } from '../../hardware/router-parsers.js';
+import { freshObservation, metricProvenance } from '../envelope.js';
+import { knownMetric, unknownMetric } from '../metric.js';
+import { createObservationDiagnostics, } from '../provenance.js';
+import { hasRawField, mergeRawRecords, prefixRawRecord, rawBooleanAt, rawKey, rawNumber, rawNumberAt, rawString, rawStringArray, } from '../raw.js';
+const SOURCE = 'modemmanager';
+const MODEM = 'Modem';
+const MODEM3GPP = 'Modem3gpp';
+const SIM = 'Sim';
+const SIGNAL = 'Signal';
+export function normalizeModemManagerObservation(input, context) {
+    const raw = mergeRawRecords(prefixRawRecord(MODEM, input.modem), prefixRawRecord(MODEM3GPP, input.modem3gpp), prefixRawRecord(SIM, input.sim), prefixRawRecord(SIGNAL, input.signal));
+    const notes = [];
+    const consumed = [];
+    const provenance = (...fields) => {
+        consumed.push(...fields);
+        return metricProvenance(SOURCE, context, fields);
+    };
+    const hardware = normalizeHardware(raw, provenance);
+    const radio = normalizeRadio(raw, provenance, notes);
+    const signal = normalizeSignal(raw, input.signal !== undefined, provenance);
+    const sim = normalizeSim(raw, input.sim !== undefined, provenance, notes);
+    return freshObservation(SOURCE, context, {
+        source: SOURCE,
+        hardware,
+        radio,
+        signal,
+        sim,
+        diagnostics: createObservationDiagnostics({ source: SOURCE, raw, consumed, notes }),
+    });
+}
+const MODEL = rawKey(MODEM, 'Model');
+const MANUFACTURER = rawKey(MODEM, 'Manufacturer');
+const REVISION = rawKey(MODEM, 'Revision');
+const EQUIPMENT_ID = rawKey(MODEM, 'EquipmentIdentifier');
+const STATE = rawKey(MODEM, 'State');
+const CURRENT_MODES = rawKey(MODEM, 'CurrentModes');
+const ACCESS_TECHNOLOGIES = rawKey(MODEM, 'AccessTechnologies');
+const SIGNAL_QUALITY = rawKey(MODEM, 'SignalQuality');
+const SIM_PATH = rawKey(MODEM, 'Sim');
+const SIM_SLOTS = rawKey(MODEM, 'SimSlots');
+const FAILED_REASON = rawKey(MODEM, 'StateFailedReason');
+const UNLOCK_REQUIRED = rawKey(MODEM, 'UnlockRequired');
+const REGISTRATION_STATE = rawKey(MODEM3GPP, 'RegistrationState');
+const SIM_TYPE = rawKey(SIM, 'SimType');
+const ESIM_STATUS = rawKey(SIM, 'EsimStatus');
+const RSSI = rawKey(SIGNAL, 'rssi');
+const RSRP = rawKey(SIGNAL, 'rsrp');
+const RSRQ = rawKey(SIGNAL, 'rsrq');
+const SNR = rawKey(SIGNAL, 'snr');
+function hardwareIdentity(raw) {
+    const model = rawString(raw, MODEL);
+    const manufacturer = rawString(raw, MANUFACTURER);
+    const firmwareRevision = rawString(raw, REVISION);
+    const equipmentId = rawString(raw, EQUIPMENT_ID);
+    return {
+        ...(model === undefined ? {} : { model }),
+        ...(manufacturer === undefined ? {} : { manufacturer }),
+        ...(firmwareRevision === undefined ? {} : { firmwareRevision }),
+        ...(equipmentId === undefined ? {} : { equipmentId }),
+    };
+}
+function normalizeHardware(raw, provenance) {
+    const identity = hardwareIdentity(raw);
+    const named = identity.model !== undefined ||
+        identity.manufacturer !== undefined ||
+        identity.firmwareRevision !== undefined;
+    const labelProvenance = provenance(MODEL, MANUFACTURER, REVISION);
+    const nameProvenance = provenance(MODEL, MANUFACTURER, REVISION, EQUIPMENT_ID);
+    return {
+        label: named
+            ? knownMetric(modemHardwareLabel(identity), labelProvenance)
+            : unknownMetric('not-reported', labelProvenance),
+        displayName: named
+            ? knownMetric(modemHardwareName(identity), nameProvenance)
+            : unknownMetric('not-reported', nameProvenance),
+    };
+}
+function normalizeRadio(raw, provenance, notes) {
+    return {
+        modemState: decodedLabel(raw, STATE, decodeMmState, provenance, notes),
+        registration: decodedLabel(raw, REGISTRATION_STATE, decodeRegistrationState, provenance, notes),
+        accessTechnologies: normalizeAccessTechnologies(raw, provenance, notes),
+        modeLabel: normalizeModeLabel(raw, provenance, notes),
+    };
+}
+/** A decoder whose "I could not place this" answer is the literal string `unknown`. */
+function decodedLabel(raw, key, decode, provenance, notes) {
+    const source = provenance(key);
+    if (!hasRawField(raw, key)) {
+        return unknownMetric('not-reported', source);
+    }
+    const decoded = decode(rawNumber(raw, key));
+    if (decoded === 'unknown') {
+        notes.push({ code: 'field-shape-unrecognized', field: key });
+        return unknownMetric('malformed', source);
+    }
+    return knownMetric(decoded, source);
+}
+function normalizeAccessTechnologies(raw, provenance, notes) {
+    const source = provenance(ACCESS_TECHNOLOGIES);
+    if (!hasRawField(raw, ACCESS_TECHNOLOGIES)) {
+        return unknownMetric('not-reported', source);
+    }
+    const mask = rawNumber(raw, ACCESS_TECHNOLOGIES);
+    // MM's 0 is `UNKNOWN` — the modem did not say, which is not a malformed answer.
+    if (mask === undefined || mask <= 0) {
+        return unknownMetric('not-reported', source);
+    }
+    const decoded = [...decodeMmAccessTechnologies(mask)].sort();
+    if (decoded.length === 0) {
+        notes.push({ code: 'field-shape-unrecognized', field: ACCESS_TECHNOLOGIES });
+        return unknownMetric('malformed', source);
+    }
+    return knownMetric(decoded, source);
+}
+function normalizeModeLabel(raw, provenance, notes) {
+    const source = provenance(CURRENT_MODES);
+    if (!hasRawField(raw, CURRENT_MODES)) {
+        return unknownMetric('not-reported', source);
+    }
+    // `CurrentModes` is a `(uu)`; the ALLOWED mask is member 0. A flattened scalar
+    // (mmcli's shape) decodes at the same index, so both retentions work here.
+    const mask = rawNumberAt(raw, CURRENT_MODES, 0);
+    if (mask === undefined || mask <= 0) {
+        return unknownMetric('not-reported', source);
+    }
+    const label = modeMaskToLabel(mask);
+    if (label === undefined) {
+        notes.push({ code: 'field-shape-unrecognized', field: CURRENT_MODES });
+        return unknownMetric('malformed', source);
+    }
+    return knownMetric(label, source);
+}
+function normalizeSignal(raw, signalRead, provenance) {
+    const missing = signalRead ? 'not-reported' : 'not-observed';
+    const extended = (key) => {
+        const source = provenance(key);
+        const value = rawNumber(raw, key);
+        return value === undefined
+            ? unknownMetric(hasRawField(raw, key) ? 'malformed' : missing, source)
+            : knownMetric(value, source);
+    };
+    // `SignalQuality` is a `(ub)`: percentage at 0, "measured recently" at 1. Both are
+    // claimed; a source that retained only the percentage answers `not-reported` for the
+    // flag, which is a claim about the READ, never about ModemManager's capability.
+    const quality = rawNumberAt(raw, SIGNAL_QUALITY, 0);
+    const recent = rawBooleanAt(raw, SIGNAL_QUALITY, 1);
+    const qualityProvenance = provenance(SIGNAL_QUALITY);
+    return {
+        quality: quality === undefined
+            ? unknownMetric('not-reported', qualityProvenance)
+            : knownMetric(quality, qualityProvenance),
+        qualityRecent: recent === undefined
+            ? unknownMetric('not-reported', provenance(SIGNAL_QUALITY))
+            : knownMetric(recent, provenance(SIGNAL_QUALITY)),
+        // ModemManager reports a percentage and no bar scale. Deriving bars from the
+        // percentage would be inventing a reading, so this is a capability claim.
+        bars: unknownMetric('unsupported', metricProvenanceEmpty(provenance)),
+        maxBars: unknownMetric('unsupported', metricProvenanceEmpty(provenance)),
+        dbm: extended(RSSI),
+        rsrp: extended(RSRP),
+        rsrq: extended(RSRQ),
+        snr: extended(SNR),
+        // `Modem.Signal` exposes rssi/rsrp/rsrq/snr/ecio/io/rscp — there is no SINR member.
+        sinr: unknownMetric('unsupported', metricProvenanceEmpty(provenance)),
+    };
+}
+/** Provenance for a metric no raw field backs, which is what `unsupported` means. */
+function metricProvenanceEmpty(provenance) {
+    return provenance();
+}
+/**
+ * `Modem.StateFailedReason` in the spelling the presence rule matches.
+ *
+ * D-Bus types it `u`, so a provider retaining the property verbatim holds a NUMBER,
+ * while the migrated rule matches the mmcli STRING. Both are accepted here — the
+ * number through the enum decoder, the string as it stands — because the two transports
+ * for the same fact must not disagree about whether a modem has a SIM. An
+ * unrecognized number decodes to `undefined` and simply proves nothing.
+ */
+function failedReasonOf(raw) {
+    const numeric = rawNumber(raw, FAILED_REASON);
+    if (numeric !== undefined)
+        return decodeStateFailedReason(numeric);
+    return rawString(raw, FAILED_REASON);
+}
+function simPresenceFacts(raw) {
+    const sim = rawString(raw, SIM_PATH);
+    const simSlots = rawStringArray(raw, SIM_SLOTS);
+    const failedReason = failedReasonOf(raw);
+    return {
+        ...(sim === undefined ? {} : { sim }),
+        ...(simSlots === undefined ? {} : { simSlots }),
+        ...(failedReason === undefined ? {} : { failedReason }),
+    };
+}
+function normalizeSim(raw, simRead, provenance, notes) {
+    const presenceProvenance = provenance(SIM_PATH, SIM_SLOTS, FAILED_REASON);
+    // `absent` here comes from `state-failed-reason` evidence and from nothing else.
+    // A blank `Sim` object path with no failure reason stays `unknown`: ModemManager
+    // reports `/` while a modem is initializing and while a slot switch is in flight,
+    // so reading it as "no SIM" would report an absent SIM on a modem holding one.
+    const { presence, evidence } = readSimPresence(simPresenceFacts(raw));
+    const missing = simRead ? 'not-reported' : 'not-observed';
+    return {
+        presence: presence === 'unknown'
+            ? unknownMetric('not-reported', presenceProvenance)
+            : knownMetric(presence, presenceProvenance),
+        presenceEvidence: evidence,
+        lockRequired: decodedOptional(raw, UNLOCK_REQUIRED, decodeUnlockRequired, provenance, notes),
+        kind: decodedOptional(raw, SIM_TYPE, decodeSimType, provenance, notes, missing),
+        esimStatus: decodedOptional(raw, ESIM_STATUS, decodeEsimStatus, provenance, notes, missing),
+    };
+}
+/** A decoder whose "I could not place this" answer is `undefined`. */
+function decodedOptional(raw, key, decode, provenance, notes, absentReason = 'not-reported') {
+    const source = provenance(key);
+    if (!hasRawField(raw, key)) {
+        return unknownMetric(absentReason, source);
+    }
+    const decoded = decode(rawNumber(raw, key));
+    if (decoded === undefined) {
+        notes.push({ code: 'field-shape-unrecognized', field: key });
+        return unknownMetric('malformed', source);
+    }
+    return knownMetric(decoded, source);
+}

package/dist/observations/sources/router-shared.d.ts

@@ -0,0 +1,29 @@
+import { type ObservationAuthority } from '../../domain/index.js';
+import { type NormalizedMetric } from '../metric.js';
+import type { NormalizedHardware, NormalizedSim } from '../model.js';
+import type { MetricProvenance } from '../provenance.js';
+export type RouterProvenance = (fields: readonly string[], authority?: ObservationAuthority) => MetricProvenance;
+export declare function unsupportedRadioMetric(provenance: RouterProvenance): NormalizedMetric<string>;
+/**
+ * The SIM block every router source produces.
+ *
+ * `vendorPresenceField` NAMES the vendor's own presence code when the payload carried
+ * one, so the evidence records that a code exists and was deliberately not decoded —
+ * distinct from `no-evidence`, which says the payload offered nothing at all. Neither
+ * one is ever `absent`: claiming absence from a vendor code whose semantics no
+ * migrated decoder covers is precisely the invented reading this layer refuses.
+ */
+export declare function routerSim(provenance: RouterProvenance, vendorPresenceField?: string): NormalizedSim;
+/** Router admin APIs report no measurement-recency flag; that is a source capability claim. */
+export declare function unsupportedQualityRecent(provenance: RouterProvenance): NormalizedMetric<boolean>;
+/**
+ * A router's product name, screened by the migrated presentation rules.
+ *
+ * `modemHardwareLabel` falls back to a generic label when its input says nothing, and
+ * publishing that as a KNOWN value would be reporting a name no device gave. So an
+ * uninformative product string is refused up front and reads `not-reported` instead.
+ */
+export declare function routerHardware(provenance: RouterProvenance, product: {
+    readonly name: string;
+    readonly field: string;
+} | undefined): NormalizedHardware;

package/dist/observations/sources/router-shared.js

@@ -0,0 +1,68 @@
+// The claims every router admin API makes identically, in one place.
+//
+// HiLink, goform and HIMI are three vendor HTTP surfaces over a modem, and they share
+// a capability boundary: none of them exposes ModemManager's modem state, its 3GPP
+// registration enum, its lock enum or its SIM-type enum. Those read `unsupported`,
+// which is a durable claim about the SOURCE rather than about one poll — and stating
+// it once here is what stops the three normalizers from drifting into three different
+// answers for the same structural fact.
+//
+// SIM PRESENCE is deliberately NOT claimed. Each vendor reports a presence code of
+// its own (`SimStatus`, `simcard_state`, `simstate`) with vendor semantics, and no
+// migrated decoder covers them; guessing one would be exactly the invented reading
+// this layer exists to prevent. It reads `not-reported` and the vendor code stays
+// verbatim in the diagnostics block for the per-vendor providers to claim later.
+import { isUninformativeIdentity, modemHardwareLabel, modemHardwareName, } from '../../domain/index.js';
+import { knownMetric, unknownMetric } from '../metric.js';
+export function unsupportedRadioMetric(provenance) {
+    return unknownMetric('unsupported', provenance([]));
+}
+/**
+ * The SIM block every router source produces.
+ *
+ * `vendorPresenceField` NAMES the vendor's own presence code when the payload carried
+ * one, so the evidence records that a code exists and was deliberately not decoded —
+ * distinct from `no-evidence`, which says the payload offered nothing at all. Neither
+ * one is ever `absent`: claiming absence from a vendor code whose semantics no
+ * migrated decoder covers is precisely the invented reading this layer refuses.
+ */
+export function routerSim(provenance, vendorPresenceField) {
+    // The vendor field is NAMED in the evidence but is NOT consumed: no metric claims its
+    // value, so it must stay in the diagnostics block's `unmapped` set, verbatim, for the
+    // per-vendor provider that will one day decode it with evidence.
+    return {
+        presence: unknownMetric('not-reported', provenance([])),
+        presenceEvidence: vendorPresenceField === undefined
+            ? { kind: 'no-evidence', inspected: [] }
+            : { kind: 'vendor-code-unclaimed', field: vendorPresenceField },
+        lockRequired: unknownMetric('unsupported', provenance([])),
+        kind: unknownMetric('unsupported', provenance([])),
+        esimStatus: unknownMetric('unsupported', provenance([])),
+    };
+}
+/** Router admin APIs report no measurement-recency flag; that is a source capability claim. */
+export function unsupportedQualityRecent(provenance) {
+    return unknownMetric('unsupported', provenance([]));
+}
+/**
+ * A router's product name, screened by the migrated presentation rules.
+ *
+ * `modemHardwareLabel` falls back to a generic label when its input says nothing, and
+ * publishing that as a KNOWN value would be reporting a name no device gave. So an
+ * uninformative product string is refused up front and reads `not-reported` instead.
+ */
+export function routerHardware(provenance, product) {
+    if (product === undefined || isUninformativeIdentity(product.name)) {
+        const source = provenance(product === undefined ? [] : [product.field]);
+        return {
+            label: unknownMetric('not-reported', source),
+            displayName: unknownMetric('not-reported', source),
+        };
+    }
+    const source = provenance([product.field]);
+    const identity = { model: product.name };
+    return {
+        label: knownMetric(modemHardwareLabel(identity), source),
+        displayName: knownMetric(modemHardwareName(identity), source),
+    };
+}

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

@@ -0,0 +1,10 @@
+import type { ObservationEnvelope } from '../../domain/index.js';
+import { type NormalizationContext } from '../envelope.js';
+import type { NormalizedModemObservation } from '../model.js';
+export type UfiObservationInput = {
+    readonly sysinfo: string;
+    readonly overview: string;
+    readonly status: string;
+    readonly produceInfo?: string;
+};
+export declare function normalizeUfiObservation(input: UfiObservationInput, context: NormalizationContext): ObservationEnvelope<NormalizedModemObservation>;

package/dist/observations/sources/ufi.js

@@ -0,0 +1,111 @@
+// Qualcomm UFI / HIMI → normalized observation.
+//
+// UFI answers three endpoints per read, each an envelope of its own (`{reply, params}`),
+// and the migrated `parseUfiSignal` already folds them in the vendor's own precedence
+// order. This module keeps all three bodies verbatim — including the `reply` field,
+// which is how a `SessionOut` refusal is told apart from a body that simply lacked the
+// key — and reports the ONE signal reading the source actually provides.
+//
+// Its overview endpoint returns an IMSI and an ICCID. They are retained, because
+// normalization does not get to decide what a diagnostician may need, and they are
+// masked by the shared key-based redactor on the way to anything that renders. That
+// split — retain here, redact at the boundary — is why `raw` is documented as a
+// redaction-class surface rather than as safe-by-default data.
+import { parseUfiDetails, parseUfiSignal } from '../../hardware/router-parsers.js';
+import { freshObservation, metricProvenance } from '../envelope.js';
+import { metricFromRouterSignal, unknownMetric } from '../metric.js';
+import { createObservationDiagnostics, } from '../provenance.js';
+import { hasRawField, mergeRawRecords, normalizeRawValue, parseJsonObject, prefixRawRecord, rawKey, } from '../raw.js';
+import { routerHardware, routerSim, unsupportedQualityRecent, unsupportedRadioMetric, } from './router-shared.js';
+const SOURCE = 'ufi-himiapi';
+const SYSINFO = 'sysinfo';
+const OVERVIEW = 'overview';
+const STATUS = 'status';
+const PRODUCE_INFO = 'produce-info';
+const SESSION_REFUSAL = 'SessionOut';
+/** HIMI's own SIM presence code. Named as evidence, never decoded into a presence. */
+const SIM_STATE = rawKey(SYSINFO, 'simstate');
+export function normalizeUfiObservation(input, context) {
+    const bodies = [
+        [SYSINFO, input.sysinfo],
+        [OVERVIEW, input.overview],
+        [STATUS, input.status],
+        [PRODUCE_INFO, input.produceInfo ?? ''],
+    ];
+    const notes = [];
+    const records = bodies.map(([name, text]) => {
+        const parsed = parseJsonObject(text);
+        if (parsed === undefined && text.trim() !== '') {
+            notes.push({ code: 'unparseable-body', field: name });
+        }
+        if (parsed?.reply === SESSION_REFUSAL) {
+            notes.push({ code: 'auth-expired', field: rawKey(name, 'reply') });
+        }
+        return prefixRawRecord(name, flattenUfiEnvelope(parsed));
+    });
+    const raw = mergeRawRecords(...records);
+    const consumed = [];
+    const provenance = (fields, authority) => {
+        consumed.push(...fields);
+        return authority === undefined
+            ? metricProvenance(SOURCE, context, fields)
+            : metricProvenance(SOURCE, context, fields, authority);
+    };
+    const signalModel = parseUfiSignal({
+        sysinfo: input.sysinfo,
+        overview: input.overview,
+        status: input.status,
+    });
+    const details = parseUfiDetails({
+        overview: input.overview,
+        sysinfo: input.sysinfo,
+        ...(input.produceInfo === undefined ? {} : { produceInfo: input.produceInfo }),
+    });
+    const product = details?.product;
+    return freshObservation(SOURCE, context, {
+        source: SOURCE,
+        hardware: routerHardware(provenance, product === undefined
+            ? undefined
+            : { name: product, field: rawKey(PRODUCE_INFO, 'productname') }),
+        radio: {
+            modemState: unsupportedRadioMetric(provenance),
+            registration: unsupportedRadioMetric(provenance),
+            accessTechnologies: unknownMetric('unsupported', provenance([])),
+            modeLabel: unknownMetric('not-reported', provenance([])),
+        },
+        signal: {
+            quality: unknownMetric('unsupported', provenance([])),
+            qualityRecent: unsupportedQualityRecent(provenance),
+            bars: metricFromRouterSignal(signalModel.bars, provenance([])),
+            maxBars: metricFromRouterSignal(signalModel.max_bars, provenance([])),
+            dbm: metricFromRouterSignal(signalModel.dbm, provenance([
+                rawKey(SYSINFO, 'SIGNAL'),
+                rawKey(OVERVIEW, 'SIGNAL'),
+                rawKey(STATUS, 'signalStrength'),
+            ])),
+            rsrp: metricFromRouterSignal(signalModel.rsrp, provenance([])),
+            rsrq: metricFromRouterSignal(signalModel.rsrq, provenance([])),
+            snr: metricFromRouterSignal(signalModel.snr, provenance([])),
+            sinr: metricFromRouterSignal(signalModel.sinr, provenance([])),
+        },
+        sim: routerSim(provenance, hasRawField(raw, SIM_STATE) ? SIM_STATE : undefined),
+        diagnostics: createObservationDiagnostics({ source: SOURCE, raw, consumed, notes }),
+    });
+}
+/** `{reply, params}` flattened to one level — `params` members keep their own names. */
+function flattenUfiEnvelope(parsed) {
+    const out = {};
+    if (parsed === undefined) {
+        return out;
+    }
+    for (const [key, value] of Object.entries(parsed)) {
+        if (key === 'params' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            for (const [field, param] of Object.entries(value)) {
+                out[field] = normalizeRawValue(param);
+            }
+            continue;
+        }
+        out[key] = normalizeRawValue(value);
+    }
+    return out;
+}

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

@@ -0,0 +1,7 @@
+import type { ObservationEnvelope } from '../../domain/index.js';
+import { type NormalizationContext } from '../envelope.js';
+import type { NormalizedModemObservation } from '../model.js';
+export type ZteObservationInput = {
+    readonly body: string;
+};
+export declare function normalizeZteObservation(input: ZteObservationInput, context: NormalizationContext): ObservationEnvelope<NormalizedModemObservation>;

package/dist/observations/sources/zte.js

@@ -0,0 +1,71 @@
+// ZTE goform → normalized observation.
+//
+// One goform response answers many keys at once, so the migrated `parseZteSignal` and
+// `parseZteDetails` are both driven from the SAME body here — and everything neither
+// of them claims (`wan_lte_ca`, `rmcc`, `lte_pci`, the cell id, the roaming flag) is
+// retained verbatim in the diagnostics block. That retention is the point: a
+// carrier-aggregation flag no normalized field has a slot for is still the difference
+// between a diagnosable report and a shrug.
+//
+// A body that will not parse is an OBSERVATION whose metrics are `malformed`, not an
+// unavailable one. The bytes arrived; what failed was decoding them, and an
+// unavailable envelope would have to discard them to say so.
+import { parseZteDetails, parseZteSignal } from '../../hardware/router-parsers.js';
+import { freshObservation, metricProvenance } from '../envelope.js';
+import { knownMetric, metricFromRouterSignal, unknownMetric, } from '../metric.js';
+import { createObservationDiagnostics } from '../provenance.js';
+import { hasRawField, parseJsonRecord, prefixRawRecord, rawKey } from '../raw.js';
+import { routerHardware, routerSim, unsupportedQualityRecent, unsupportedRadioMetric, } from './router-shared.js';
+const SOURCE = 'zte-goform';
+const BODY = 'goform';
+/** ZTE's own SIM presence code. Named as evidence, never decoded into a presence. */
+const SIM_CARD_STATE = rawKey(BODY, 'simcard_state');
+export function normalizeZteObservation(input, context) {
+    const parsed = parseJsonRecord(input.body);
+    const raw = prefixRawRecord(BODY, parsed);
+    const notes = [];
+    if (parsed === undefined) {
+        notes.push({ code: input.body.trim() === '' ? 'empty-body' : 'unparseable-body', field: BODY });
+    }
+    const consumed = [];
+    const provenance = (fields, authority) => {
+        consumed.push(...fields);
+        return authority === undefined
+            ? metricProvenance(SOURCE, context, fields)
+            : metricProvenance(SOURCE, context, fields, authority);
+    };
+    const signalModel = parseZteSignal(input.body);
+    const details = parseZteDetails(input.body);
+    return freshObservation(SOURCE, context, {
+        source: SOURCE,
+        hardware: routerHardware(provenance, undefined),
+        radio: {
+            modemState: unsupportedRadioMetric(provenance),
+            registration: unsupportedRadioMetric(provenance),
+            accessTechnologies: unknownMetric('unsupported', provenance([])),
+            modeLabel: normalizeModeLabel(details?.network_type, parsed !== undefined, provenance),
+        },
+        signal: {
+            quality: unknownMetric('unsupported', provenance([])),
+            qualityRecent: unsupportedQualityRecent(provenance),
+            bars: metricFromRouterSignal(signalModel.bars, provenance([rawKey(BODY, 'signalbar')], 'derived')),
+            // The goform payload carries no maximum; the migrated parser states the
+            // vendor's fixed five-bar scale, which is a derivation and says so.
+            maxBars: metricFromRouterSignal(signalModel.max_bars, provenance([], 'derived')),
+            dbm: metricFromRouterSignal(signalModel.dbm, provenance([rawKey(BODY, 'rssi')])),
+            rsrp: metricFromRouterSignal(signalModel.rsrp, provenance([rawKey(BODY, 'lte_rsrp')])),
+            rsrq: metricFromRouterSignal(signalModel.rsrq, provenance([rawKey(BODY, 'lte_rsrq')])),
+            snr: metricFromRouterSignal(signalModel.snr, provenance([rawKey(BODY, 'lte_snr')])),
+            sinr: metricFromRouterSignal(signalModel.sinr, provenance([])),
+        },
+        sim: routerSim(provenance, hasRawField(raw, SIM_CARD_STATE) ? SIM_CARD_STATE : undefined),
+        diagnostics: createObservationDiagnostics({ source: SOURCE, raw, consumed, notes }),
+    });
+}
+function normalizeModeLabel(networkType, parsed, provenance) {
+    const source = provenance([rawKey(BODY, 'network_type')]);
+    if (networkType !== undefined) {
+        return knownMetric(networkType, source);
+    }
+    return unknownMetric(parsed ? 'not-reported' : 'malformed', source);
+}

package/dist/observations/state-separation.d.ts

@@ -0,0 +1,64 @@
+import type { DeviceGeneration, EpochMillis, ObservationEnvelope } from '../domain/index.js';
+/** What an operator asked for. Not a claim that anything acted on it. */
+export type DesiredProfile<T> = {
+    readonly kind: 'desired';
+    readonly profile: T;
+    readonly requestedAt: EpochMillis;
+    /** Opaque origin label (an RPC caller, a policy engine). Never a credential. */
+    readonly requestedBy: string;
+};
+/** What was actually put into force, and by which operation, in which generation. */
+export type AppliedConfiguration<T> = {
+    readonly kind: 'applied';
+    readonly configuration: T;
+    readonly appliedAt: EpochMillis;
+    readonly generation: DeviceGeneration;
+    readonly operationId: string;
+};
+/** What the device itself reports — always through an envelope, never bare. */
+export type ObservedState<T> = {
+    readonly kind: 'observed';
+    readonly observation: ObservationEnvelope<T>;
+};
+export declare function desiredProfile<T>(profile: T, requestedAt: EpochMillis, requestedBy: string): DesiredProfile<T>;
+export declare function appliedConfiguration<T>(input: {
+    readonly configuration: T;
+    readonly appliedAt: EpochMillis;
+    readonly generation: DeviceGeneration;
+    readonly operationId: string;
+}): AppliedConfiguration<T>;
+export declare function observedState<T>(observation: ObservationEnvelope<T>): ObservedState<T>;
+/**
+ * The three-slot view. There is deliberately no fourth field holding a merged
+ * "effective" value: an effective value is a RENDERING decision, and computing one
+ * here would bake a policy every consumer would then have to work around.
+ */
+export type ModemStateView<TDesired, TApplied, TObserved> = {
+    readonly desired: DesiredProfile<TDesired> | null;
+    readonly applied: AppliedConfiguration<TApplied> | null;
+    readonly observed: ObservedState<TObserved>;
+};
+export declare const STATE_VIEW_SLOTS: readonly ["desired", "applied", "observed"];
+export type StateViewSlot = (typeof STATE_VIEW_SLOTS)[number];
+export type SlotComparison = {
+    readonly status: 'aligned';
+} | {
+    readonly status: 'diverged';
+}
+/** One side has nothing to compare — NOT the same as agreeing. */
+ | {
+    readonly status: 'indeterminate';
+    readonly missing: StateViewSlot;
+};
+/**
+ * Two independent comparisons, never one verdict.
+ *
+ * `desiredVsApplied` answers "did our write happen"; `appliedVsObserved` answers "did
+ * it stick". A single boolean cannot distinguish a request that was never carried out
+ * from one the network undid a second later, and those need opposite responses.
+ */
+export type StateDivergence = {
+    readonly desiredVsApplied: SlotComparison;
+    readonly appliedVsObserved: SlotComparison;
+};
+export declare function describeStateDivergence<T>(view: ModemStateView<T, T, T>, equals: (left: T, right: T) => boolean): StateDivergence;