@ceralive/modem-control 1.2.1 → 1.4.0

package/dist/observations/sources/modemmanager.js

@@ -8,35 +8,45 @@
 // 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 { decode3gppLacCi, 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';
+import { hasRawDictMember, hasRawField, mergeRawRecords, prefixRawRecord, rawBooleanAt, rawDictNumber, rawKey, rawNumber, rawNumberAt, rawString, rawStringArray, } from '../raw.js';
 const SOURCE = 'modemmanager';
 const MODEM = 'Modem';
 const MODEM3GPP = 'Modem3gpp';
 const SIM = 'Sim';
 const SIGNAL = 'Signal';
+const LOCATION = 'Location';
 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 raw = mergeRawRecords(prefixRawRecord(MODEM, input.modem), prefixRawRecord(MODEM3GPP, input.modem3gpp), prefixRawRecord(SIM, input.sim), prefixRawRecord(SIGNAL, input.signal), prefixRawRecord(LOCATION, input.location));
     const notes = [];
     const consumed = [];
     const provenance = (...fields) => {
         consumed.push(...fields);
         return metricProvenance(SOURCE, context, fields);
     };
+    // A dict-sourced metric CONSUMES the whole `a{sv}` property (that is the raw key it
+    // actually has) while NAMING the exact member it read, so provenance stays precise
+    // without `unmapped` gaining a key that was never in the payload.
+    const dictProvenance = (dict, member) => {
+        consumed.push(dict);
+        return metricProvenance(SOURCE, context, [`${dict}.${member}`]);
+    };
     const hardware = normalizeHardware(raw, provenance);
     const radio = normalizeRadio(raw, provenance, notes);
-    const signal = normalizeSignal(raw, input.signal !== undefined, provenance);
+    const signal = normalizeSignal(raw, input.signal !== undefined, provenance, dictProvenance, notes);
     const sim = normalizeSim(raw, input.sim !== undefined, provenance, notes);
+    const cell = normalizeCell(raw, input.location !== undefined, provenance, notes);
     return freshObservation(SOURCE, context, {
         source: SOURCE,
         hardware,
         radio,
         signal,
         sim,
+        cell,
         diagnostics: createObservationDiagnostics({ source: SOURCE, raw, consumed, notes }),
     });
 }
@@ -53,12 +63,53 @@ 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 OPERATOR_NAME = rawKey(MODEM3GPP, 'OperatorName');
+const OPERATOR_CODE = rawKey(MODEM3GPP, 'OperatorCode');
 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');
+// The `Modem.Location` entry for MM's coarse-cell source. Named, not bit-keyed — see
+// `ModemManagerObservationInput.location`.
+const LAC_CI = rawKey(LOCATION, '3gpp-lac-ci');
+// `Modem.Signal` publishes ONE `a{sv}` per RAT, and the member sets differ (MM 1.24.2
+// `org.freedesktop.ModemManager1.Modem.Signal.xml`):
+//   Cdma rssi/ecio/error-rate       Evdo rssi/ecio/SINR/io/error-rate
+//   Gsm  rssi/error-rate            Umts rssi/rscp/ecio/error-rate
+//   Lte  rssi/rsrq/rsrp/snr/error-rate    Nr5g rsrq/rsrp/snr/error-rate
+const SIGNAL_CDMA = rawKey(SIGNAL, 'Cdma');
+const SIGNAL_EVDO = rawKey(SIGNAL, 'Evdo');
+const SIGNAL_GSM = rawKey(SIGNAL, 'Gsm');
+const SIGNAL_UMTS = rawKey(SIGNAL, 'Umts');
+const SIGNAL_LTE = rawKey(SIGNAL, 'Lte');
+const SIGNAL_NR5G = rawKey(SIGNAL, 'Nr5g');
+const RSSI = {
+    member: 'rssi',
+    dicts: [SIGNAL_LTE, SIGNAL_UMTS, SIGNAL_GSM, SIGNAL_EVDO, SIGNAL_CDMA],
+    flat: rawKey(SIGNAL, 'rssi'),
+};
+const RSRP = {
+    member: 'rsrp',
+    dicts: [SIGNAL_NR5G, SIGNAL_LTE],
+    flat: rawKey(SIGNAL, 'rsrp'),
+};
+const RSRQ = {
+    member: 'rsrq',
+    dicts: [SIGNAL_NR5G, SIGNAL_LTE],
+    flat: rawKey(SIGNAL, 'rsrq'),
+};
+const SNR = {
+    member: 'snr',
+    dicts: [SIGNAL_NR5G, SIGNAL_LTE],
+    flat: rawKey(SIGNAL, 'snr'),
+};
+// SINR is a member of the `Evdo` dict and of NO other, so an LTE/NR modem reporting no
+// SINR is a READ-class `not-reported` — ModemManager CAN express it, this modem did not.
+// The NR SINR a device may publish through `Modem.GetCellInfo` is a different call on a
+// different interface and is deliberately not folded in here.
+const SINR = {
+    member: 'sinr',
+    dicts: [SIGNAL_EVDO],
+    flat: rawKey(SIGNAL, 'sinr'),
+};
 function hardwareIdentity(raw) {
     const model = rawString(raw, MODEL);
     const manufacturer = rawString(raw, MANUFACTURER);
@@ -93,6 +144,53 @@ function normalizeRadio(raw, provenance, notes) {
         registration: decodedLabel(raw, REGISTRATION_STATE, decodeRegistrationState, provenance, notes),
         accessTechnologies: normalizeAccessTechnologies(raw, provenance, notes),
         modeLabel: normalizeModeLabel(raw, provenance, notes),
+        // `Modem3gpp`, never `Sim` — the registered operator, not the SIM's home one.
+        // A modem that is not registered reports these empty, which is `not-reported`:
+        // the property exists and this read carried no value.
+        operatorName: registrationString(raw, OPERATOR_NAME, provenance),
+        operatorCode: registrationString(raw, OPERATOR_CODE, provenance),
+    };
+}
+/** A `Modem3gpp` registration string — present-and-empty is still no reading. */
+function registrationString(raw, key, provenance) {
+    const source = provenance(key);
+    const value = rawString(raw, key);
+    return value === undefined
+        ? unknownMetric('not-reported', source)
+        : knownMetric(value, source);
+}
+/**
+ * Coarse cell context from the `3gpp-lac-ci` location reading.
+ *
+ * The whole value is ONE string, so a `cellId` and a `tac` read out of it necessarily
+ * agree with each other — they came from the same reported cell, never from two reads
+ * that raced. A value in an unrecognized shape is `malformed` for both rather than
+ * partially decoded; see `decode3gppLacCi`.
+ */
+function normalizeCell(raw, locationRead, provenance, notes) {
+    const source = provenance(LAC_CI);
+    if (!hasRawField(raw, LAC_CI)) {
+        const reason = locationRead ? 'not-reported' : 'not-observed';
+        return {
+            cellId: unknownMetric(reason, source),
+            tac: unknownMetric(reason, source),
+        };
+    }
+    const decoded = decode3gppLacCi(rawString(raw, LAC_CI));
+    if (decoded === undefined) {
+        notes.push({ code: 'field-shape-unrecognized', field: LAC_CI });
+        return {
+            cellId: unknownMetric('malformed', source),
+            tac: unknownMetric('malformed', source),
+        };
+    }
+    return {
+        cellId: knownMetric(decoded.cellId, source),
+        // MM emits an EMPTY tracking-area code on a device with no LTE/NR attach — the
+        // reading arrived, this field of it did not.
+        tac: decoded.trackingAreaCode === ''
+            ? unknownMetric('not-reported', source)
+            : knownMetric(decoded.trackingAreaCode, source),
     };
 }
 /** A decoder whose "I could not place this" answer is the literal string `unknown`. */
@@ -143,13 +241,24 @@ function normalizeModeLabel(raw, provenance, notes) {
     }
     return knownMetric(label, source);
 }
-function normalizeSignal(raw, signalRead, provenance) {
+function normalizeSignal(raw, signalRead, provenance, dictProvenance, notes) {
     const missing = signalRead ? 'not-reported' : 'not-observed';
-    const extended = (key) => {
-        const source = provenance(key);
-        const value = rawNumber(raw, key);
+    const extended = (metric) => {
+        for (const dict of metric.dicts) {
+            if (!hasRawDictMember(raw, dict, metric.member))
+                continue;
+            const source = dictProvenance(dict, metric.member);
+            const value = rawDictNumber(raw, dict, metric.member);
+            if (value === undefined) {
+                notes.push({ code: 'field-shape-unrecognized', field: `${dict}.${metric.member}` });
+                return unknownMetric('malformed', source);
+            }
+            return knownMetric(value, source);
+        }
+        const source = provenance(metric.flat);
+        const value = rawNumber(raw, metric.flat);
         return value === undefined
-            ? unknownMetric(hasRawField(raw, key) ? 'malformed' : missing, source)
+            ? unknownMetric(hasRawField(raw, metric.flat) ? 'malformed' : missing, source)
             : knownMetric(value, source);
     };
     // `SignalQuality` is a `(ub)`: percentage at 0, "measured recently" at 1. Both are
@@ -173,8 +282,7 @@ function normalizeSignal(raw, signalRead, provenance) {
         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)),
+        sinr: extended(SINR),
     };
 }
 /** Provenance for a metric no raw field backs, which is what `unsupported` means. */

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

@@ -1,6 +1,6 @@
 import { type ObservationAuthority } from '../../domain/index.js';
 import { type NormalizedMetric } from '../metric.js';
-import type { NormalizedHardware, NormalizedSim } from '../model.js';
+import type { NormalizedCell, 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>;
@@ -14,6 +14,40 @@ export declare function unsupportedRadioMetric(provenance: RouterProvenance): No
  * migrated decoder covers is precisely the invented reading this layer refuses.
  */
 export declare function routerSim(provenance: RouterProvenance, vendorPresenceField?: string): NormalizedSim;
+/**
+ * The cell block a router source produces.
+ *
+ * `cellId` is claimed only when a MIGRATED parser decoded one — `parseZteDetails` and
+ * `parseUfiDetails` both do — and the raw vendor key is named in provenance. HiLink
+ * ships a `<cell_id>` tag that no migrated parser reads, so it stays verbatim in the
+ * diagnostics block rather than being lifted here: the same rule that keeps `SimStatus`
+ * out of `sim.presence`.
+ *
+ * `tac` is always `not-reported`, never `unsupported`. None of the three migrated
+ * parsers decodes a tracking-area code, but that is a fact about what THIS package
+ * reads, not a claim that the vendor's firmware cannot report one — and `unsupported`
+ * would be the second kind of statement.
+ */
+export declare function routerCell(provenance: RouterProvenance, cell: {
+    readonly id: string;
+    readonly field: string;
+} | undefined): NormalizedCell;
+/**
+ * A registered-operator NAME a migrated parser decoded, or an honest silence.
+ *
+ * The matching CODE is deliberately never derived. `parseZteDetails` reports `mcc` and
+ * `mnc` as separate unpadded vendor fields, while `Modem3gpp.OperatorCode` is a
+ * fixed-width concatenation that MM itself splits back apart at exactly three
+ * characters — joining an unpadded 2-vs-3-digit MNC would name a different network
+ * roughly whenever the leading zero matters. So it reads `not-reported`.
+ */
+export declare function routerOperator(provenance: RouterProvenance, operator: {
+    readonly name: string;
+    readonly field: string;
+} | undefined): {
+    readonly operatorName: NormalizedMetric<string>;
+    readonly operatorCode: NormalizedMetric<string>;
+};
 /** Router admin APIs report no measurement-recency flag; that is a source capability claim. */
 export declare function unsupportedQualityRecent(provenance: RouterProvenance): NormalizedMetric<boolean>;
 /**

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

@@ -40,6 +40,45 @@ export function routerSim(provenance, vendorPresenceField) {
         esimStatus: unknownMetric('unsupported', provenance([])),
     };
 }
+/**
+ * The cell block a router source produces.
+ *
+ * `cellId` is claimed only when a MIGRATED parser decoded one — `parseZteDetails` and
+ * `parseUfiDetails` both do — and the raw vendor key is named in provenance. HiLink
+ * ships a `<cell_id>` tag that no migrated parser reads, so it stays verbatim in the
+ * diagnostics block rather than being lifted here: the same rule that keeps `SimStatus`
+ * out of `sim.presence`.
+ *
+ * `tac` is always `not-reported`, never `unsupported`. None of the three migrated
+ * parsers decodes a tracking-area code, but that is a fact about what THIS package
+ * reads, not a claim that the vendor's firmware cannot report one — and `unsupported`
+ * would be the second kind of statement.
+ */
+export function routerCell(provenance, cell) {
+    return {
+        cellId: cell === undefined
+            ? unknownMetric('not-reported', provenance([]))
+            : knownMetric(cell.id, provenance([cell.field])),
+        tac: unknownMetric('not-reported', provenance([])),
+    };
+}
+/**
+ * A registered-operator NAME a migrated parser decoded, or an honest silence.
+ *
+ * The matching CODE is deliberately never derived. `parseZteDetails` reports `mcc` and
+ * `mnc` as separate unpadded vendor fields, while `Modem3gpp.OperatorCode` is a
+ * fixed-width concatenation that MM itself splits back apart at exactly three
+ * characters — joining an unpadded 2-vs-3-digit MNC would name a different network
+ * roughly whenever the leading zero matters. So it reads `not-reported`.
+ */
+export function routerOperator(provenance, operator) {
+    return {
+        operatorName: operator === undefined
+            ? unknownMetric('not-reported', provenance([]))
+            : knownMetric(operator.name, provenance([operator.field])),
+        operatorCode: unknownMetric('not-reported', provenance([])),
+    };
+}
 /** Router admin APIs report no measurement-recency flag; that is a source capability claim. */
 export function unsupportedQualityRecent(provenance) {
     return unknownMetric('unsupported', provenance([]));

package/dist/observations/sources/ufi.js

@@ -16,7 +16,7 @@ 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';
+import { routerCell, routerHardware, routerOperator, routerSim, unsupportedQualityRecent, unsupportedRadioMetric, } from './router-shared.js';
 const SOURCE = 'ufi-himiapi';
 const SYSINFO = 'sysinfo';
 const OVERVIEW = 'overview';
@@ -72,6 +72,9 @@ export function normalizeUfiObservation(input, context) {
             registration: unsupportedRadioMetric(provenance),
             accessTechnologies: unknownMetric('unsupported', provenance([])),
             modeLabel: unknownMetric('not-reported', provenance([])),
+            // `parseUfiDetails` decodes no operator field from any of the three
+            // endpoints, so neither half is claimed.
+            ...routerOperator(provenance, undefined),
         },
         signal: {
             quality: unknownMetric('unsupported', provenance([])),
@@ -89,6 +92,9 @@ export function normalizeUfiObservation(input, context) {
             sinr: metricFromRouterSignal(signalModel.sinr, provenance([])),
         },
         sim: routerSim(provenance, hasRawField(raw, SIM_STATE) ? SIM_STATE : undefined),
+        cell: routerCell(provenance, details?.cell_id === undefined
+            ? undefined
+            : { id: details.cell_id, field: rawKey(SYSINFO, 'cellid') }),
         diagnostics: createObservationDiagnostics({ source: SOURCE, raw, consumed, notes }),
     });
 }

package/dist/observations/sources/zte.js

@@ -15,7 +15,7 @@ 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';
+import { routerCell, routerHardware, routerOperator, 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. */
@@ -44,6 +44,9 @@ export function normalizeZteObservation(input, context) {
             registration: unsupportedRadioMetric(provenance),
             accessTechnologies: unknownMetric('unsupported', provenance([])),
             modeLabel: normalizeModeLabel(details?.network_type, parsed !== undefined, provenance),
+            ...routerOperator(provenance, details?.provider === undefined
+                ? undefined
+                : { name: details.provider, field: rawKey(BODY, 'network_provider_fullname') }),
         },
         signal: {
             quality: unknownMetric('unsupported', provenance([])),
@@ -59,6 +62,9 @@ export function normalizeZteObservation(input, context) {
             sinr: metricFromRouterSignal(signalModel.sinr, provenance([])),
         },
         sim: routerSim(provenance, hasRawField(raw, SIM_CARD_STATE) ? SIM_CARD_STATE : undefined),
+        cell: routerCell(provenance, details?.cell_id === undefined
+            ? undefined
+            : { id: details.cell_id, field: rawKey(BODY, 'cell_id') }),
         diagnostics: createObservationDiagnostics({ source: SOURCE, raw, consumed, notes }),
     });
 }

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

@@ -11,6 +11,16 @@ export interface ModemManagerProviderOptions {
     readonly destination?: string;
     readonly quiesce?: QuiesceHook;
     readonly now?: () => number;
+    /**
+     * `Signal.Setup` reporting rate in whole seconds, defaulting to
+     * `DEFAULT_SIGNAL_INTERVAL_SECONDS` (5).
+     *
+     * The backend has accepted this since it was written; the provider had no way to pass
+     * it, so an embedder constructing a provider — which is every embedder — was pinned to
+     * the default with no seam to change it. That is the gap this closes, and it is why
+     * the option is threaded rather than re-implemented here.
+     */
+    readonly signalIntervalSeconds?: 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

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

@@ -33,6 +33,9 @@ export class ModemManagerProvider {
             destination: this.#destination,
             actor,
             now: this.#now,
+            ...(options.signalIntervalSeconds === undefined
+                ? {}
+                : { signalIntervalSeconds: options.signalIntervalSeconds }),
         });
         const location = new MmLocation({
             transport: this.#transport,

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

@@ -6,10 +6,16 @@ import { decodeStateFailedReason, epochMillis, sourceEpoch, stableKeyFromPhysica
 import { readSimPresence } from '../../hardware/router-parsers.js';
 import { normalizeModemManagerObservation } from '../../observations/index.js';
 import { describeBandWriteCertification, readRadioModeTruth } from '../../radio/index.js';
+import { isVariant } from '../../transport/index.js';
 const SIGNAL_IFACE = `${MODEM_IFACE}.Signal`;
 function rawValue(value) {
     if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
         return value;
+    // An `a{sv}` decodes to `[key, variant][]`, so a dict member's value arrives WRAPPED.
+    // Without this unwrap a `Modem.Signal` RAT dict retained as `[['rsrp'], ['rsrq'], …]`:
+    // the key survived and the reading did not.
+    if (isVariant(value))
+        return rawValue(value.value);
     if (Array.isArray(value)) {
         const result = [];
         for (const item of value) {

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

@@ -20,20 +20,13 @@
 //    deactivate. There is deliberately no delete path here: profile removal is not in
 //    that set, so this adapter cannot express it.
 import { epochMillis } from '../../domain/index.js';
-import { appliedConfiguration, describeStateDivergence, desiredProfile, freshObservation, observedState, unavailableObservation, } from '../../observations/index.js';
+import { appliedConfiguration, desiredProfile } from '../../observations/index.js';
 import { receipt } from '../../ports/index.js';
-import { boundBearer, nmBearerStateEquals, unboundBearer } from './types.js';
-const SOURCE = 'networkmanager';
-/** The device states in which NM is still settling an activation, not losing it. */
-const TRANSITIONAL_STATES = new Set([
-    'prepare',
-    'config',
-    'need-auth',
-    'ip-config',
-    'ip-check',
-    'secondaries',
-    'deactivating',
-]);
+import { projectDivergence } from './divergence.js';
+import { foldObservation } from './observe-fold.js';
+import { projectStateView } from './projection.js';
+import { slotsFor, targetIfname } from './state.js';
+import { boundBearer, unboundBearer } from './types.js';
 export class NetworkManagerAdapter {
     #port;
     #now;
@@ -79,7 +72,7 @@ export class NetworkManagerAdapter {
             autoConfig: request.profile.autoConfig,
             homeOnly: request.profile.homeOnly,
         }), epochMillis(this.#now()), request.requestedBy);
-        this.#slotsFor(id).desired = desired;
+        slotsFor(this.#slots, id).desired = desired;
         return { ok: true, connectionId: id, desired };
     }
     /**
@@ -100,7 +93,7 @@ export class NetworkManagerAdapter {
             };
         }
         const desired = desiredProfile(unboundBearer(ifname), epochMillis(this.#now()), requestedBy);
-        this.#slotsFor(id).desired = desired;
+        slotsFor(this.#slots, id).desired = desired;
         return { ok: true, connectionId: id, desired };
     }
     desiredFor(id) {
@@ -151,40 +144,9 @@ export class NetworkManagerAdapter {
      * was.
      */
     observe(input) {
-        const generation = input.context.generation;
-        if (this.#observedGeneration !== null && generation < this.#observedGeneration) {
-            return {
-                kind: 'refused',
-                reason: 'superseded-generation',
-                currentGeneration: this.#observedGeneration,
-            };
-        }
-        this.#observedGeneration = generation;
-        const devices = new Map(input.devices.map((device) => [device.ifname, device]));
-        const outcomes = [];
-        const losses = [];
-        for (const [id, slots] of this.#slots) {
-            const ifname = targetIfname(slots);
-            if (ifname === undefined) {
-                continue;
-            }
-            const device = devices.get(ifname);
-            slots.observed = observedState(device === undefined
-                ? unavailableObservation(SOURCE, input.context, 'device-absent')
-                : freshObservation(SOURCE, input.context, observedBearer(device)));
-            const outcome = this.#classify(id, slots, ifname, device, input.context.observedAt);
-            outcomes.push({ connectionId: id, outcome });
-            if (outcome.status === 'lost') {
-                losses.push(outcome.loss);
-            }
-        }
-        return {
-            kind: 'accepted',
-            generation,
-            observedAt: input.context.observedAt,
-            outcomes,
-            losses,
-        };
+        const folded = foldObservation(this.#slots, this.#observedGeneration, input);
+        this.#observedGeneration = folded.generation;
+        return folded.result;
     }
     observedFor(id) {
         return this.#slots.get(id)?.observed ?? null;
@@ -195,21 +157,11 @@ export class NetworkManagerAdapter {
      * for observations, so it cannot manufacture one.
      */
     stateView(id, context) {
-        const slots = this.#slots.get(id);
-        if (slots === undefined) {
-            return null;
-        }
-        return {
-            desired: slots.desired,
-            applied: slots.applied,
-            observed: slots.observed ??
-                observedState(unavailableObservation(SOURCE, context, 'provider-unavailable')),
-        };
+        return projectStateView(this.#slots, id, context);
     }
     /** `desiredVsApplied` ("did our write happen") and `appliedVsObserved` ("did it stick"). */
     divergence(id, context) {
-        const view = this.stateView(id, context);
-        return view === null ? null : describeStateDivergence(view, nmBearerStateEquals);
+        return projectDivergence(this.#slots, id, context);
     }
     // ── internals ──────────────────────────────────────────────────────────────
     async #activate(id, desired, options) {
@@ -243,7 +195,7 @@ export class NetworkManagerAdapter {
             generation: options.generation,
             operationId: options.operationId,
         });
-        this.#slotsFor(id).applied = applied;
+        slotsFor(this.#slots, id).applied = applied;
         return { ok: true, applied, receipt: activation };
     }
     async #deactivate(id, ifname, options) {
@@ -263,82 +215,9 @@ export class NetworkManagerAdapter {
             generation: options.generation,
             operationId: options.operationId,
         });
-        this.#slotsFor(id).applied = applied;
+        slotsFor(this.#slots, id).applied = applied;
         return { ok: true, applied, receipt: result };
     }
-    #classify(id, slots, ifname, device, observedAt) {
-        const applied = slots.applied;
-        if (applied === null) {
-            return { status: 'unapplied' };
-        }
-        const lose = (reason) => {
-            slots.applied = null;
-            return {
-                status: 'lost',
-                loss: {
-                    connectionId: id,
-                    deviceIfname: ifname,
-                    reason,
-                    lostAt: observedAt,
-                    generation: applied.generation,
-                    previous: applied,
-                },
-            };
-        };
-        if (device === undefined) {
-            return lose('interface-absent');
-        }
-        if (device.state === 'failed') {
-            return lose('activation-failed');
-        }
-        if (applied.configuration.kind === 'unbound') {
-            // We deliberately took the bearer down; anything active here is somebody else.
-            return device.activeConnection === undefined
-                ? { status: 'retained', applied }
-                : lose('connection-replaced');
-        }
-        if (device.activeConnection === undefined) {
-            return lose('interface-detached');
-        }
-        if (device.activeConnection.connectionId !== id) {
-            return lose('connection-replaced');
-        }
-        if (device.state === 'activated') {
-            return { status: 'retained', applied };
-        }
-        return TRANSITIONAL_STATES.has(device.state)
-            ? { status: 'pending', applied, deviceState: device.state }
-            : lose('interface-detached');
-    }
-    #slotsFor(id) {
-        const existing = this.#slots.get(id);
-        if (existing !== undefined) {
-            return existing;
-        }
-        const created = { desired: null, applied: null, observed: null };
-        this.#slots.set(id, created);
-        return created;
-    }
-}
-/** The device the slots are about: where the bearer IS, else where it was asked for. */
-function targetIfname(slots) {
-    const state = slots.applied?.configuration ?? slots.desired?.profile;
-    if (state === undefined) {
-        return undefined;
-    }
-    return state.kind === 'bound' ? state.binding.deviceIfname : state.deviceIfname;
-}
-function observedBearer(device) {
-    const active = device.activeConnection;
-    return active === undefined
-        ? unboundBearer(device.ifname)
-        : boundBearer({
-            connectionId: active.connectionId,
-            deviceIfname: device.ifname,
-            apn: active.apn,
-            autoConfig: active.autoConfig,
-            homeOnly: active.homeOnly,
-        });
 }
 function refuse(reason, message) {
     return { ok: false, reason, receipt: receipt('connection', 'failed', message) };

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

@@ -0,0 +1,4 @@
+import type { NormalizationContext, StateDivergence } from '../../observations/index.js';
+import type { ConnectionId } from '../../ports/index.js';
+import type { ConnectionSlots } from './state.js';
+export declare function projectDivergence(slotsByConnection: ReadonlyMap<ConnectionId, ConnectionSlots>, id: ConnectionId, context: NormalizationContext): StateDivergence | null;

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

@@ -0,0 +1,7 @@
+import { describeStateDivergence } from '../../observations/index.js';
+import { projectStateView } from './projection.js';
+import { nmBearerStateEquals } from './types.js';
+export function projectDivergence(slotsByConnection, id, context) {
+    const view = projectStateView(slotsByConnection, id, context);
+    return view === null ? null : describeStateDivergence(view, nmBearerStateEquals);
+}

package/dist/providers/network-manager/observe-fold.d.ts

@@ -0,0 +1,9 @@
+import type { DeviceGeneration } from '../../domain/index.js';
+import type { ConnectionId } from '../../ports/index.js';
+import type { ConnectionSlots } from './state.js';
+import type { NmObservationInput, NmObservationResult } from './types.js';
+export interface ObservationFold {
+    readonly generation: DeviceGeneration;
+    readonly result: NmObservationResult;
+}
+export declare function foldObservation(slotsByConnection: Map<ConnectionId, ConnectionSlots>, observedGeneration: DeviceGeneration | null, input: NmObservationInput): ObservationFold;