@ceralive/modem-control 0.2.0 → 1.1.0

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;

package/dist/observations/raw.js

@@ -0,0 +1,146 @@
+// Raw-payload helpers — the retention half of normalization.
+//
+// Every normalizer builds ONE flat `RawFieldRecord` out of whatever bodies it was
+// handed, keyed by `<body>.<provider-native field>`, and reads its metrics out of
+// that same record. Reading from the retained copy rather than from the original
+// bodies is what makes the no-drop property hold by construction instead of by
+// discipline: a field a metric consumed is necessarily a field the diagnostics block
+// already carries.
+export function rawKey(body, field) {
+    return `${body}.${field}`;
+}
+/** Prefix a provider's flat record with the body it came from. */
+export function prefixRawRecord(body, record) {
+    const out = {};
+    for (const [field, value] of Object.entries(record ?? {})) {
+        out[rawKey(body, field)] = value;
+    }
+    return out;
+}
+export function mergeRawRecords(...records) {
+    return Object.assign({}, ...records);
+}
+export function rawString(record, key) {
+    const value = record[key];
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed === '' ? undefined : trimmed;
+    }
+    return typeof value === 'number' || typeof value === 'boolean' ? String(value) : undefined;
+}
+export function rawNumber(record, key) {
+    const value = record[key];
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (typeof value !== 'string' || value.trim() === '') {
+        return undefined;
+    }
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+export function rawStringArray(record, key) {
+    const value = record[key];
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : undefined;
+}
+export function hasRawField(record, key) {
+    return Object.hasOwn(record, key);
+}
+/**
+ * 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 function rawStructMember(record, key, index) {
+    const value = record[key];
+    if (Array.isArray(value))
+        return value[index];
+    return index === 0 ? value : undefined;
+}
+export function rawNumberAt(record, key, index) {
+    const member = rawStructMember(record, key, index);
+    if (typeof member === 'number')
+        return Number.isFinite(member) ? member : undefined;
+    if (typeof member !== 'string' || member.trim() === '')
+        return undefined;
+    const parsed = Number.parseFloat(member);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+export function rawBooleanAt(record, key, index) {
+    const member = rawStructMember(record, key, index);
+    return typeof member === 'boolean' ? member : undefined;
+}
+const XML_LEAF = /<([A-Za-z_][\w.-]*)>([^<]*)<\/\1>/g;
+/**
+ * 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 function flattenXmlBody(body, name) {
+    const out = {};
+    const seen = new Map();
+    for (const match of body.matchAll(XML_LEAF)) {
+        const tag = match[1] ?? '';
+        const count = (seen.get(tag) ?? 0) + 1;
+        seen.set(tag, count);
+        out[rawKey(name, count === 1 ? tag : `${tag}#${count}`)] = (match[2] ?? '').trim();
+    }
+    return out;
+}
+/** Parse a JSON object body, or `undefined` when the bytes are not a JSON object. */
+export function parseJsonObject(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError)) {
+            throw error;
+        }
+        return undefined;
+    }
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+        ? parsed
+        : undefined;
+}
+/** Parse a JSON object body into a flat record, or `undefined` when it is not one. */
+export function parseJsonRecord(body) {
+    const parsed = parseJsonObject(body);
+    if (parsed === undefined) {
+        return undefined;
+    }
+    const out = {};
+    for (const [field, value] of Object.entries(parsed)) {
+        out[field] = normalizeRawValue(value);
+    }
+    return out;
+}
+/**
+ * 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 function normalizeRawValue(value) {
+    if (value === null) {
+        return null;
+    }
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(normalizeRawValue);
+    }
+    // A nested object has no flat representation; keep its JSON text rather than drop it.
+    return JSON.stringify(value);
+}

package/dist/observations/reading.d.ts

@@ -0,0 +1,51 @@
+import type { DeviceGeneration, EpochMillis, ObservationAuthority, ObservationEnvelope, SourceEpoch, StableKey } from '../domain/index.js';
+import { type ObservationStaleReason, type ObservationUnavailableReason } from './envelope.js';
+import type { MetricUnknownReason, NormalizedMetric } from './metric.js';
+import type { MetricProvenance } from './provenance.js';
+/** The envelope-level provenance every reading carries, whatever its state. */
+export type EnvelopeProvenance = {
+    readonly stableKey: StableKey;
+    readonly generation: DeviceGeneration;
+    readonly source: string;
+    readonly sourceEpoch: SourceEpoch;
+    readonly observedAt: EpochMillis;
+    readonly authority: ObservationAuthority;
+};
+export declare function envelopeProvenance<T>(envelope: ObservationEnvelope<T>): EnvelopeProvenance;
+type ReadingBase = {
+    readonly envelope: EnvelopeProvenance;
+};
+export type ObservationReading<T> = (ReadingBase & {
+    readonly state: 'fresh';
+    readonly value: T;
+    readonly provenance: MetricProvenance;
+}) | (ReadingBase & {
+    readonly state: 'stale';
+    readonly value: T;
+    readonly since: EpochMillis;
+    readonly reason: ObservationStaleReason;
+    readonly provenance: MetricProvenance;
+}) | (ReadingBase & {
+    readonly state: 'unavailable';
+    readonly since: EpochMillis;
+    readonly reason: ObservationUnavailableReason;
+}) | (ReadingBase & {
+    readonly state: 'unknown';
+    readonly reason: MetricUnknownReason;
+    readonly provenance: MetricProvenance;
+});
+export declare const OBSERVATION_READING_STATES: readonly ["fresh", "stale", "unavailable", "unknown"];
+export type ObservationReadingState = (typeof OBSERVATION_READING_STATES)[number];
+/**
+ * Project one metric out of an envelope.
+ *
+ * An unknown metric inside a STALE envelope reads `unknown`, not `stale`: staleness is
+ * a statement about a value's age, and there is no value here to have aged. The
+ * envelope's own age remains readable through `reading.envelope.observedAt`.
+ */
+export declare function readMetric<T, V>(envelope: ObservationEnvelope<T>, select: (value: T) => NormalizedMetric<V>): ObservationReading<V>;
+/** Whether a reading carries a value a consumer may render. */
+export declare function hasReadableValue<T>(reading: ObservationReading<T>): reading is Extract<ObservationReading<T>, {
+    readonly state: 'fresh' | 'stale';
+}>;
+export {};

package/dist/observations/reading.js

@@ -0,0 +1,65 @@
+// Reading — the projection a consumer renders from.
+//
+// It is the one place the envelope's freshness and the metric's knownness are folded
+// together, and it keeps FOUR genuinely distinct outcomes rather than a value plus a
+// flag:
+//
+//   `fresh`       — a current value.
+//   `stale`       — a RETAINED value that has aged out, with when and why.
+//   `unavailable` — there is no observation at all; no value exists to report.
+//   `unknown`     — there IS an observation and this field is not in it, with a reason
+//                   that says whether the source CANNOT report it or merely DID NOT.
+//
+// They differ in shape, not only in label: `unavailable` and `unknown` carry no
+// `value` field at all, so no consumer can read one off a state that has none, and
+// `unavailable` carries no metric provenance because no metric was produced.
+import { viewEnvelope, } from './envelope.js';
+export function envelopeProvenance(envelope) {
+    return {
+        stableKey: envelope.stableKey,
+        generation: envelope.generation,
+        source: envelope.source,
+        sourceEpoch: envelope.sourceEpoch,
+        observedAt: envelope.observedAt,
+        authority: envelope.authority,
+    };
+}
+export const OBSERVATION_READING_STATES = ['fresh', 'stale', 'unavailable', 'unknown'];
+/**
+ * Project one metric out of an envelope.
+ *
+ * An unknown metric inside a STALE envelope reads `unknown`, not `stale`: staleness is
+ * a statement about a value's age, and there is no value here to have aged. The
+ * envelope's own age remains readable through `reading.envelope.observedAt`.
+ */
+export function readMetric(envelope, select) {
+    const base = { envelope: envelopeProvenance(envelope) };
+    const view = viewEnvelope(envelope);
+    if (view.kind === 'unavailable') {
+        return {
+            ...base,
+            state: 'unavailable',
+            since: view.freshness.since,
+            reason: view.freshness.reason,
+        };
+    }
+    const metric = select(view.value);
+    if (metric.state === 'unknown') {
+        return { ...base, state: 'unknown', reason: metric.reason, provenance: metric.provenance };
+    }
+    if (view.freshness.state === 'stale') {
+        return {
+            ...base,
+            state: 'stale',
+            value: metric.value,
+            since: view.freshness.since,
+            reason: view.freshness.reason,
+            provenance: metric.provenance,
+        };
+    }
+    return { ...base, state: 'fresh', value: metric.value, provenance: metric.provenance };
+}
+/** Whether a reading carries a value a consumer may render. */
+export function hasReadableValue(reading) {
+    return reading.state === 'fresh' || reading.state === 'stale';
+}

package/dist/observations/sources/hilink.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 HilinkObservationInput = {
+    readonly status: string;
+    readonly signal: string;
+    readonly netModeList?: string;
+    readonly netMode?: string;
+};
+export declare function normalizeHilinkObservation(input: HilinkObservationInput, context: NormalizationContext): ObservationEnvelope<NormalizedModemObservation>;

package/dist/observations/sources/hilink.js

@@ -0,0 +1,84 @@
+// Huawei HiLink admin API → normalized observation.
+//
+// The decoding is the migrated `parseHilinkSignal` / `parseHilinkCapabilities`; this
+// module adds provenance, retains both XML bodies field-for-field, and states the
+// capability boundary honestly. HiLink is a ROUTER admin API, not a modem stack: it
+// has no ModemManager state, no 3GPP registration state and no access-technology
+// bitmask, so those read `unsupported` — a claim about this source, which stays true
+// on the next poll — while a field the API could carry and did not reads
+// `not-reported`.
+//
+// Its `<ConnectionStatus>` and `<SimStatus>` are NOT folded into `radio.registration`
+// or `sim.presence`. They are vendor codes with vendor semantics and no migrated
+// decoder claims them, so they stay verbatim in the diagnostics block instead of
+// being guessed into a normalized field.
+import { parseHilinkCapabilities, parseHilinkSignal } from '../../hardware/router-parsers.js';
+import { freshObservation, metricProvenance } from '../envelope.js';
+import { knownMetric, metricFromRouterSignal, metricUnknownReasonFromRouter, unknownMetric, } from '../metric.js';
+import { createObservationDiagnostics } from '../provenance.js';
+import { flattenXmlBody, hasRawField, mergeRawRecords, rawKey } from '../raw.js';
+import { routerHardware, routerSim, unsupportedQualityRecent, unsupportedRadioMetric, } from './router-shared.js';
+const SOURCE = 'huawei-hilink';
+const STATUS = 'monitoring-status';
+const SIGNAL = 'device-signal';
+const NET_MODE_LIST = 'net-mode-list';
+const NET_MODE = 'net-mode';
+/** HiLink's own SIM presence code. Named as evidence, never decoded into a presence. */
+const SIM_STATUS = rawKey(STATUS, 'SimStatus');
+const AUTH_REFUSAL_CODE = '125002';
+export function normalizeHilinkObservation(input, context) {
+    const raw = mergeRawRecords(flattenXmlBody(input.status, STATUS), flattenXmlBody(input.signal, SIGNAL), flattenXmlBody(input.netModeList ?? '', NET_MODE_LIST), flattenXmlBody(input.netMode ?? '', NET_MODE));
+    const notes = [];
+    const consumed = [];
+    const provenance = (fields, authority) => {
+        consumed.push(...fields);
+        return authority === undefined
+            ? metricProvenance(SOURCE, context, fields)
+            : metricProvenance(SOURCE, context, fields, authority);
+    };
+    for (const [body, text] of [
+        [STATUS, input.status],
+        [SIGNAL, input.signal],
+    ]) {
+        if (text.includes(`<code>${AUTH_REFUSAL_CODE}</code>`)) {
+            notes.push({ code: 'auth-expired', field: rawKey(body, 'code') });
+        }
+    }
+    const signalModel = parseHilinkSignal({ status: input.status, signal: input.signal });
+    const capabilities = parseHilinkCapabilities({
+        netModeList: input.netModeList ?? '',
+        ...(input.netMode === undefined ? {} : { netMode: input.netMode }),
+    });
+    return freshObservation(SOURCE, context, {
+        source: SOURCE,
+        hardware: routerHardware(provenance, undefined),
+        radio: {
+            modemState: unsupportedRadioMetric(provenance),
+            registration: unsupportedRadioMetric(provenance),
+            accessTechnologies: unknownMetric('unsupported', provenance([])),
+            modeLabel: normalizeModeLabel(capabilities.net_mode, provenance),
+        },
+        signal: {
+            quality: unknownMetric('unsupported', provenance([])),
+            qualityRecent: unsupportedQualityRecent(provenance),
+            bars: metricFromRouterSignal(signalModel.bars, provenance([rawKey(STATUS, 'SignalIcon')], 'derived')),
+            maxBars: metricFromRouterSignal(signalModel.max_bars, provenance([rawKey(STATUS, 'maxsignal')], 'derived')),
+            dbm: metricFromRouterSignal(signalModel.dbm, provenance([rawKey(SIGNAL, 'rssi')])),
+            rsrp: metricFromRouterSignal(signalModel.rsrp, provenance([rawKey(SIGNAL, 'rsrp')])),
+            rsrq: metricFromRouterSignal(signalModel.rsrq, provenance([rawKey(SIGNAL, 'rsrq')])),
+            snr: metricFromRouterSignal(signalModel.snr, provenance([])),
+            sinr: metricFromRouterSignal(signalModel.sinr, provenance([rawKey(SIGNAL, 'sinr')])),
+        },
+        sim: routerSim(provenance, hasRawField(raw, SIM_STATUS) ? SIM_STATUS : undefined),
+        diagnostics: createObservationDiagnostics({ source: SOURCE, raw, consumed, notes }),
+    });
+}
+function normalizeModeLabel(capability, provenance) {
+    const source = provenance([rawKey(NET_MODE, 'NetworkMode')]);
+    if (capability.state === 'unavailable') {
+        return unknownMetric(metricUnknownReasonFromRouter(capability.reason), source);
+    }
+    return capability.current === undefined
+        ? unknownMetric('not-reported', source)
+        : knownMetric(capability.current, source);
+}