@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/observations/freshness.js

@@ -0,0 +1,76 @@
+// Freshness evaluation — how a retained observation ages, and what it never becomes.
+//
+// Three rules carry the weight here:
+//
+//  1. **Staleness keeps the value.** An aged reading is the last thing the device
+//     actually said; discarding it leaves an operator with a blank field and no way
+//     to tell "we lost contact" from "the modem reports nothing".
+//  2. **Unavailable is terminal on re-evaluation.** An envelope that carries no value
+//     cannot become stale, because there is nothing to age. Re-classifying it would
+//     have to invent a value to be stale about.
+//  3. **Staleness is monotonic.** A stale envelope is returned UNCHANGED, so its
+//     `since` and `reason` record the FIRST cause. Freshness comes from a new read,
+//     never from re-evaluating an old one.
+//
+// This module has no clock: the caller supplies `at` on every evaluation, which is
+// what makes the whole window testable without waiting. Same discipline as
+// `location/fix-state.ts`.
+import { epochMillis, isCurrentGeneration, } from '../domain/index.js';
+import { viewEnvelope } from './envelope.js';
+/** How long ago an envelope was observed, floored at zero for a clock that moved back. */
+export function observationAgeMs(envelope, at) {
+    return Math.max(0, at - envelope.observedAt);
+}
+/**
+ * Re-classify an envelope against the current time, epoch, generation and source
+ * health.
+ *
+ * Trigger precedence, when several apply at once: superseded generation → superseded
+ * source epoch → degraded source → TTL expiry. The first three are positive statements
+ * that the reading has been overtaken by a newer reality; TTL expiry only says nobody
+ * has looked recently, and reporting it over a supersession would understate why.
+ */
+export function evaluateFreshness(envelope, evaluation) {
+    const view = viewEnvelope(envelope);
+    if (view.kind === 'unavailable' || view.freshness.state !== 'fresh') {
+        return envelope;
+    }
+    const reason = staleReason(envelope, evaluation);
+    if (reason === undefined) {
+        return envelope;
+    }
+    return {
+        ...envelope,
+        freshness: { state: 'stale', since: staleSince(envelope, evaluation, reason), reason },
+        value: view.value,
+    };
+}
+function staleReason(envelope, evaluation) {
+    if (evaluation.currentGeneration !== undefined &&
+        !isCurrentGeneration(envelope.generation, evaluation.currentGeneration)) {
+        return 'source-epoch-superseded';
+    }
+    if (evaluation.currentSourceEpoch !== undefined &&
+        envelope.sourceEpoch !== evaluation.currentSourceEpoch) {
+        return 'source-epoch-superseded';
+    }
+    if (evaluation.sourceHealthy === false) {
+        return 'source-degraded';
+    }
+    return observationAgeMs(envelope, evaluation.at) > evaluation.window.ttlMs
+        ? 'ttl-expired'
+        : undefined;
+}
+/**
+ * When the reading became stale.
+ *
+ * A TTL expiry has an exact moment — one window after it was observed — and reporting
+ * the evaluation time instead would make a reading that expired an hour ago look like
+ * it just went stale. A supersession or a degradation is only known at the moment it
+ * is evaluated, so those honestly report `at`.
+ */
+function staleSince(envelope, evaluation, reason) {
+    return reason === 'ttl-expired'
+        ? epochMillis(envelope.observedAt + evaluation.window.ttlMs)
+        : evaluation.at;
+}

package/dist/observations/index.d.ts

@@ -0,0 +1,13 @@
+export * from './envelope.js';
+export * from './freshness.js';
+export * from './metric.js';
+export * from './model.js';
+export * from './provenance.js';
+export * from './raw.js';
+export * from './reading.js';
+export * from './sources/hilink.js';
+export * from './sources/modemmanager.js';
+export * from './sources/router-shared.js';
+export * from './sources/ufi.js';
+export * from './sources/zte.js';
+export * from './state-separation.js';

package/dist/observations/index.js

@@ -0,0 +1,24 @@
+// The observation layer — normalization, provenance, freshness.
+//
+// It sits directly on top of the migrated pure logic (`domain/mm-enums.ts`,
+// `domain/modem-presentation.ts`, `hardware/router-parsers.ts`) and turns a raw
+// per-vendor payload into ONE `ObservationEnvelope<NormalizedModemObservation>` that
+// carries where every value came from and why any value is missing. It opens no
+// transport: a provider performs the read, this layer explains the result.
+//
+// Reachable through the package root, deliberately not through a new subpath — the
+// public specifier set is a frozen contract and this is normalization, which the root
+// entry already owns.
+export * from './envelope.js';
+export * from './freshness.js';
+export * from './metric.js';
+export * from './model.js';
+export * from './provenance.js';
+export * from './raw.js';
+export * from './reading.js';
+export * from './sources/hilink.js';
+export * from './sources/modemmanager.js';
+export * from './sources/router-shared.js';
+export * from './sources/ufi.js';
+export * from './sources/zte.js';
+export * from './state-separation.js';

package/dist/observations/metric.d.ts

@@ -0,0 +1,61 @@
+import type { RouterSignalMetric, RouterSignalUnknownReason } from '../hardware/router-parsers.js';
+import type { MetricProvenance } from './provenance.js';
+export declare const METRIC_UNKNOWN_REASONS: readonly [
+/** A positive claim about the SOURCE: it cannot express this datum at all. */
+'unsupported', 
+/** The source answered and simply did not include this field. */
+'not-reported', 
+/** Nobody has read this yet. Says nothing about the source or the device. */
+'not-observed', 
+/** The source answered with something this layer could not decode. */
+'malformed', 
+/** The source refused the read; the session needs re-authentication. */
+'auth-expired', 
+/** The source answered with an explicit refusal code for this field. */
+'refused', 
+/** The source could not be reached for this read. */
+'unreachable'];
+export type MetricUnknownReason = (typeof METRIC_UNKNOWN_REASONS)[number];
+/**
+ * The two classes an unknown reason falls into.
+ *
+ * `capability` is a durable statement about the source; `read` is a statement about
+ * one attempt and may differ on the next one. A consumer deciding whether to HIDE a
+ * control (capability) or show it as pending (read) must branch on this, never on the
+ * bare fact that a value is missing.
+ */
+export type MetricUnknownClass = 'capability' | 'read';
+export declare function metricUnknownClass(reason: MetricUnknownReason): MetricUnknownClass;
+/** Whether a reason is the positive "this source cannot report it" claim. */
+export declare function isCapabilityUnknown(reason: MetricUnknownReason): reason is 'unsupported';
+export type NormalizedMetric<T> = {
+    readonly state: 'known';
+    readonly value: T;
+    readonly provenance: MetricProvenance;
+} | {
+    readonly state: 'unknown';
+    readonly reason: MetricUnknownReason;
+    readonly provenance: MetricProvenance;
+};
+export declare function knownMetric<T>(value: T, provenance: MetricProvenance): NormalizedMetric<T>;
+export declare function unknownMetric<T>(reason: MetricUnknownReason, provenance: MetricProvenance): NormalizedMetric<T>;
+/**
+ * Lift an optional decode result into a metric.
+ *
+ * `reason` is supplied by the caller precisely so this helper cannot pick one: the
+ * difference between "the provider omitted the field" and "this provider has no such
+ * field" is knowledge the decoder does not have and the call site does.
+ */
+export declare function metricFromOptional<T>(value: T | undefined, reason: MetricUnknownReason, provenance: MetricProvenance): NormalizedMetric<T>;
+/**
+ * The migrated router parsers' own unknown vocabulary, carried across UNCHANGED.
+ *
+ * Every member of `RouterSignalUnknownReason` is a member of `MetricUnknownReason`
+ * with the same meaning, so this is a widening and never a re-classification — in
+ * particular `not-reported` stays `not-reported` and does not become `unsupported`.
+ */
+export declare function metricUnknownReasonFromRouter(reason: RouterSignalUnknownReason | 'refused'): MetricUnknownReason;
+/** Wrap one migrated router signal metric with its provenance. */
+export declare function metricFromRouterSignal(metric: RouterSignalMetric, provenance: MetricProvenance): NormalizedMetric<number>;
+/** Transform a known value while preserving state, reason and provenance. */
+export declare function mapMetric<T, U>(metric: NormalizedMetric<T>, transform: (value: T) => U): NormalizedMetric<U>;

package/dist/observations/metric.js

@@ -0,0 +1,73 @@
+// A normalized metric: a value, or an explicit reason there is none — with the
+// provenance of the exact reading that produced it.
+//
+// `unknown` is a FIRST-CLASS state here, and its reason is what keeps it from
+// collapsing into `unsupported`. Those two answer different questions: `unsupported`
+// is a positive claim about the SOURCE ("this provider cannot express this datum at
+// all"), while every other reason is a claim about one READ ("the provider could have
+// said, and did not / could not be asked / answered nonsense"). Folding the second
+// class into the first is how a control disappears from an operator's screen because
+// one poll came back empty.
+export const METRIC_UNKNOWN_REASONS = [
+    /** A positive claim about the SOURCE: it cannot express this datum at all. */
+    'unsupported',
+    /** The source answered and simply did not include this field. */
+    'not-reported',
+    /** Nobody has read this yet. Says nothing about the source or the device. */
+    'not-observed',
+    /** The source answered with something this layer could not decode. */
+    'malformed',
+    /** The source refused the read; the session needs re-authentication. */
+    'auth-expired',
+    /** The source answered with an explicit refusal code for this field. */
+    'refused',
+    /** The source could not be reached for this read. */
+    'unreachable',
+];
+export function metricUnknownClass(reason) {
+    return reason === 'unsupported' ? 'capability' : 'read';
+}
+/** Whether a reason is the positive "this source cannot report it" claim. */
+export function isCapabilityUnknown(reason) {
+    return metricUnknownClass(reason) === 'capability';
+}
+export function knownMetric(value, provenance) {
+    return { state: 'known', value, provenance };
+}
+export function unknownMetric(reason, provenance) {
+    return { state: 'unknown', reason, provenance };
+}
+/**
+ * Lift an optional decode result into a metric.
+ *
+ * `reason` is supplied by the caller precisely so this helper cannot pick one: the
+ * difference between "the provider omitted the field" and "this provider has no such
+ * field" is knowledge the decoder does not have and the call site does.
+ */
+export function metricFromOptional(value, reason, provenance) {
+    return value === undefined
+        ? unknownMetric(reason, provenance)
+        : knownMetric(value, provenance);
+}
+/**
+ * The migrated router parsers' own unknown vocabulary, carried across UNCHANGED.
+ *
+ * Every member of `RouterSignalUnknownReason` is a member of `MetricUnknownReason`
+ * with the same meaning, so this is a widening and never a re-classification — in
+ * particular `not-reported` stays `not-reported` and does not become `unsupported`.
+ */
+export function metricUnknownReasonFromRouter(reason) {
+    return reason;
+}
+/** Wrap one migrated router signal metric with its provenance. */
+export function metricFromRouterSignal(metric, provenance) {
+    return metric.state === 'known'
+        ? knownMetric(metric.value, provenance)
+        : unknownMetric(metricUnknownReasonFromRouter(metric.reason), provenance);
+}
+/** Transform a known value while preserving state, reason and provenance. */
+export function mapMetric(metric, transform) {
+    return metric.state === 'known'
+        ? knownMetric(transform(metric.value), metric.provenance)
+        : unknownMetric(metric.reason, metric.provenance);
+}

package/dist/observations/model.d.ts

@@ -0,0 +1,80 @@
+import type { RadioAccessTechnology } from '../domain/index.js';
+import type { SimPresenceEvidence } from '../hardware/router-parsers.js';
+import type { NormalizedMetric } from './metric.js';
+import type { ObservationDiagnostics, ObservationSourceKind } from './provenance.js';
+export type NormalizedHardware = {
+    /** The operator-facing model label, sanitized by the migrated presentation rules. */
+    readonly label: NormalizedMetric<string>;
+    /**
+     * The label plus a short equipment-identifier tail, as CeraUI has always rendered
+     * it. It embeds the last five digits of an IMEI, so it is display copy and must
+     * not be used as a key or written to a log.
+     */
+    readonly displayName: NormalizedMetric<string>;
+};
+export type NormalizedRadio = {
+    readonly modemState: NormalizedMetric<string>;
+    readonly registration: NormalizedMetric<string>;
+    readonly accessTechnologies: NormalizedMetric<readonly RadioAccessTechnology[]>;
+    readonly modeLabel: NormalizedMetric<string>;
+};
+/**
+ * Signal metrics.
+ *
+ * `quality` and `bars`/`maxBars` are different measurements and both are kept:
+ * ModemManager reports a 0-100 percentage and no bar count, while the router admin
+ * APIs report a vendor bar scale and no percentage. Deriving one from the other would
+ * be inventing a reading, so each source reports what it has and answers
+ * `unsupported` — a positive claim — for what it structurally cannot.
+ */
+export type NormalizedSignal = {
+    readonly quality: NormalizedMetric<number>;
+    /**
+     * ModemManager's `SignalQuality` is a `(ub)` — a percentage AND a boolean saying
+     * whether it was measured recently or is the last cached reading. The boolean is a
+     * separate fact about the same measurement, so it gets its own metric rather than
+     * being folded into freshness: an envelope's staleness is about when WE read, this
+     * is about when the MODEM last measured. The router APIs have no such flag and say
+     * so with `unsupported`.
+     */
+    readonly qualityRecent: NormalizedMetric<boolean>;
+    readonly bars: NormalizedMetric<number>;
+    readonly maxBars: NormalizedMetric<number>;
+    readonly dbm: NormalizedMetric<number>;
+    readonly rsrp: NormalizedMetric<number>;
+    readonly rsrq: NormalizedMetric<number>;
+    readonly snr: NormalizedMetric<number>;
+    readonly sinr: NormalizedMetric<number>;
+};
+/**
+ * SIM presence as a metric value is BINARY on purpose.
+ *
+ * The migrated `deriveSimPresence` answers `present | absent | unknown`; the third
+ * member is not a presence, it is the absence of an answer, so it becomes the
+ * metric's `unknown` state with a reason instead of a third value. That is what stops
+ * "we could not tell" from being rendered beside "there is no SIM".
+ */
+export type SimPresenceValue = 'present' | 'absent';
+export type NormalizedSim = {
+    readonly presence: NormalizedMetric<SimPresenceValue>;
+    /**
+     * WHICH FACT decided `presence`. Carried beside the metric rather than derived from
+     * it, because "absent" and "we could not tell" are read off the SAME empty fields
+     * and only the evidence separates them. `absent` is reachable through exactly one
+     * evidence kind (`state-failed-reason`), which is what makes "never inferred from a
+     * blank field" a property a test can assert rather than a convention.
+     */
+    readonly presenceEvidence: SimPresenceEvidence;
+    readonly lockRequired: NormalizedMetric<string>;
+    readonly kind: NormalizedMetric<'physical' | 'esim'>;
+    readonly esimStatus: NormalizedMetric<'no-profiles' | 'with-profiles'>;
+};
+export type NormalizedModemObservation = {
+    readonly source: ObservationSourceKind;
+    readonly hardware: NormalizedHardware;
+    readonly radio: NormalizedRadio;
+    readonly signal: NormalizedSignal;
+    readonly sim: NormalizedSim;
+    /** Everything the provider said, verbatim, plus what was and was not claimed. */
+    readonly diagnostics: ObservationDiagnostics;
+};

package/dist/observations/model.js

@@ -0,0 +1,11 @@
+// The normalized observation shape every source produces.
+//
+// It is deliberately NARROW. A field earns a slot here only when more than one source
+// can express it and an operator surface acts on it; everything else stays verbatim in
+// the diagnostics block rather than growing a per-vendor branch of the model. That is
+// the whole trade this layer makes — one shape to render, nothing thrown away.
+//
+// Every leaf is a `NormalizedMetric`, so "the source cannot report this" and "the
+// source did not report this on this read" are different values with different
+// reasons rather than the same absent field.
+export {};

package/dist/observations/provenance.d.ts

@@ -0,0 +1,94 @@
+import type { EpochMillis, ObservationAuthority, SourceEpoch } from '../domain/index.js';
+/**
+ * The provider families this layer normalizes.
+ *
+ * These are SOURCE SHAPES, not live transports. Todo 18 builds the normalization
+ * layer; the providers that will feed it (ModemManager D-Bus, the HiLink/goform/HIMI
+ * HTTP sessions) are separate work and open no connection from here.
+ *
+ * `networkmanager` is here because NM is a source of a DIFFERENT fact than the other
+ * four: it reports which connection is in force on which interface, never a radio
+ * reading. Giving it its own kind is what keeps a bearer observation attributable to
+ * NM rather than laundered through whichever provider happened to read the modem.
+ */
+export declare const OBSERVATION_SOURCE_KINDS: readonly ['modemmanager', 'huawei-hilink', 'zte-goform', 'ufi-himiapi', 'networkmanager'];
+export type ObservationSourceKind = (typeof OBSERVATION_SOURCE_KINDS)[number];
+/**
+ * A provider-native value, kept exactly as the provider expressed it.
+ *
+ * Arrays are part of the union because ModemManager genuinely returns them
+ * (`Modem.SimSlots` is an `ao`); flattening one to its first member here would be a
+ * silent drop of exactly the kind this module exists to prevent.
+ */
+export type RawFieldValue = string | number | boolean | null | readonly RawFieldValue[];
+/** Provider-native fields keyed by their provider-native names. */
+export type RawFieldRecord = Readonly<Record<string, RawFieldValue>>;
+/**
+ * Per-metric provenance: which source, which reading of it, and when.
+ *
+ * It is carried on EVERY metric rather than only on the envelope because one
+ * normalized observation routinely folds several provider reads together (HiLink
+ * answers `device_signal` and `monitoring_status` separately; UFI answers three
+ * endpoints), so a single envelope-level `observedAt` would be a claim about a
+ * reading no individual metric came from.
+ */
+export type MetricProvenance = {
+    readonly source: ObservationSourceKind;
+    readonly sourceEpoch: SourceEpoch;
+    readonly observedAt: EpochMillis;
+    readonly authority: ObservationAuthority;
+    /** The provider-native field name(s) this value was normalized from. */
+    readonly rawFields: readonly string[];
+};
+/**
+ * Structural complaints about a payload. A note names the FIELD or body it concerns
+ * and never carries its value: a body can hold an ICCID or a one-time code, and a
+ * diagnostic is the one place a reviewer reads verbatim.
+ */
+export declare const OBSERVATION_DIAGNOSTIC_CODES: readonly ['unparseable-body', 'empty-body', 'auth-expired', 'field-shape-unrecognized'];
+export type ObservationDiagnosticCode = (typeof OBSERVATION_DIAGNOSTIC_CODES)[number];
+export type ObservationDiagnosticNote = {
+    readonly code: ObservationDiagnosticCode;
+    /** The provider-native field or body name, never its content. */
+    readonly field: string;
+};
+/**
+ * The typed diagnostics block: the provider payload, verbatim, plus which fields the
+ * normalizer claimed and which it did not.
+ *
+ * `raw` is a REDACTION-CLASS boundary. A vendor payload routinely carries an ICCID or
+ * an IMSI (the UFI overview endpoint reports both), so anything that logs, serializes
+ * or files a diagnostics block must route it through {@link redactObservationDiagnostics}
+ * first. Retention and disclosure are different decisions; this layer only guarantees
+ * the first.
+ */
+export type ObservationDiagnostics = {
+    readonly source: ObservationSourceKind;
+    /** Every provider-native field, verbatim. Nothing is dropped during normalization. */
+    readonly raw: RawFieldRecord;
+    /** Fields a normalized metric claims. They remain present in `raw` as well. */
+    readonly consumed: readonly string[];
+    /** Fields in `raw` that no normalized field claims — retained, never discarded. */
+    readonly unmapped: readonly string[];
+    readonly notes: readonly ObservationDiagnosticNote[];
+};
+export type DiagnosticsInput = {
+    readonly source: ObservationSourceKind;
+    readonly raw: RawFieldRecord;
+    readonly consumed?: readonly string[];
+    readonly notes?: readonly ObservationDiagnosticNote[];
+};
+/**
+ * Build a diagnostics block, deriving `unmapped` rather than accepting it.
+ *
+ * Deriving it is what makes the no-drop property structural: a normalizer cannot
+ * declare a field mapped without a metric that names it, and a field it never
+ * mentions lands in `unmapped` automatically instead of vanishing.
+ */
+export declare function createObservationDiagnostics(input: DiagnosticsInput): ObservationDiagnostics;
+/**
+ * A copy of `diagnostics` with every sensitive raw field replaced by the shared
+ * redaction marker. Routed through the package's own key-based `redact`, so the
+ * classes it masks here are exactly the classes it masks everywhere else.
+ */
+export declare function redactObservationDiagnostics(diagnostics: ObservationDiagnostics): ObservationDiagnostics;

package/dist/observations/provenance.js

@@ -0,0 +1,67 @@
+// Provenance + diagnostics — where a normalized value came from, and everything the
+// provider said that the normalized model has no field for.
+//
+// The rule this module exists to enforce: normalization NARROWS a vendor payload into
+// one shape, it does not DISCARD it. Every provider-native field a normalizer reads —
+// and every one it does not — is retained verbatim in `ObservationDiagnostics.raw`,
+// and each normalized metric carries the provenance of the exact observation that
+// produced it. A consumer can therefore always answer "which provider said this, and
+// when" without the provider having to widen the normalized model.
+import { redact } from '../redact.js';
+/**
+ * The provider families this layer normalizes.
+ *
+ * These are SOURCE SHAPES, not live transports. Todo 18 builds the normalization
+ * layer; the providers that will feed it (ModemManager D-Bus, the HiLink/goform/HIMI
+ * HTTP sessions) are separate work and open no connection from here.
+ *
+ * `networkmanager` is here because NM is a source of a DIFFERENT fact than the other
+ * four: it reports which connection is in force on which interface, never a radio
+ * reading. Giving it its own kind is what keeps a bearer observation attributable to
+ * NM rather than laundered through whichever provider happened to read the modem.
+ */
+export const OBSERVATION_SOURCE_KINDS = [
+    'modemmanager',
+    'huawei-hilink',
+    'zte-goform',
+    'ufi-himiapi',
+    'networkmanager',
+];
+/**
+ * Structural complaints about a payload. A note names the FIELD or body it concerns
+ * and never carries its value: a body can hold an ICCID or a one-time code, and a
+ * diagnostic is the one place a reviewer reads verbatim.
+ */
+export const OBSERVATION_DIAGNOSTIC_CODES = [
+    'unparseable-body',
+    'empty-body',
+    'auth-expired',
+    'field-shape-unrecognized',
+];
+/**
+ * Build a diagnostics block, deriving `unmapped` rather than accepting it.
+ *
+ * Deriving it is what makes the no-drop property structural: a normalizer cannot
+ * declare a field mapped without a metric that names it, and a field it never
+ * mentions lands in `unmapped` automatically instead of vanishing.
+ */
+export function createObservationDiagnostics(input) {
+    const rawKeys = Object.keys(input.raw);
+    const consumed = [...new Set(input.consumed ?? [])].filter((key) => rawKeys.includes(key)).sort();
+    const consumedSet = new Set(consumed);
+    return {
+        source: input.source,
+        raw: input.raw,
+        consumed,
+        unmapped: rawKeys.filter((key) => !consumedSet.has(key)).sort(),
+        notes: input.notes ?? [],
+    };
+}
+/**
+ * A copy of `diagnostics` with every sensitive raw field replaced by the shared
+ * redaction marker. Routed through the package's own key-based `redact`, so the
+ * classes it masks here are exactly the classes it masks everywhere else.
+ */
+export function redactObservationDiagnostics(diagnostics) {
+    return { ...diagnostics, raw: redact(diagnostics.raw) };
+}

package/dist/observations/raw.d.ts

@@ -0,0 +1,42 @@
+import type { RawFieldRecord, RawFieldValue } from './provenance.js';
+export declare function rawKey(body: string, field: string): string;
+/** Prefix a provider's flat record with the body it came from. */
+export declare function prefixRawRecord(body: string, record: Readonly<Record<string, RawFieldValue>> | undefined): RawFieldRecord;
+export declare function mergeRawRecords(...records: readonly RawFieldRecord[]): RawFieldRecord;
+export declare function rawString(record: RawFieldRecord, key: string): string | undefined;
+export declare function rawNumber(record: RawFieldRecord, key: string): number | undefined;
+export declare function rawStringArray(record: RawFieldRecord, key: string): readonly string[] | undefined;
+export declare function hasRawField(record: RawFieldRecord, key: string): boolean;
+/**
+ * One member of a D-Bus STRUCT retained verbatim.
+ *
+ * ModemManager's `SignalQuality` is a `(ub)` and its `CurrentModes` is a `(uu)`, so
+ * retaining them verbatim means the raw record holds an ARRAY where a naive read
+ * expects a scalar. A caller that flattened the struct before retention would keep the
+ * first member and silently drop the second — the recency flag, and the preferred mode
+ * — which is the drop this layer exists to prevent. A scalar answers at index 0, so a
+ * source that already flattened (mmcli, or a pre-existing fixture) still decodes.
+ */
+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;
+/**
+ * Flatten every leaf element of an XML body into `<body>.<Tag>` entries.
+ *
+ * A repeated tag — HiLink's `<NetworkMode>` list repeats `<Index>` once per mode —
+ * would otherwise overwrite its predecessors, so the second and later occurrences are
+ * suffixed `#2`, `#3`, …. Losing a repeat is exactly the silent drop this layer
+ * exists to prevent, and the suffix keeps the original tag name legible.
+ */
+export declare function flattenXmlBody(body: string, name: string): RawFieldRecord;
+/** Parse a JSON object body, or `undefined` when the bytes are not a JSON object. */
+export declare function parseJsonObject(body: string): Readonly<Record<string, unknown>> | undefined;
+/** Parse a JSON object body into a flat record, or `undefined` when it is not one. */
+export declare function parseJsonRecord(body: string): Readonly<Record<string, RawFieldValue>> | undefined;
+/**
+ * A nested object has no flat representation, so its JSON text is kept.
+ *
+ * Serializing rather than dropping is the whole contract of this layer: a payload
+ * this record cannot model structurally is still a payload a diagnostician can read.
+ */
+export declare function normalizeRawValue(value: unknown): RawFieldValue;