@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/location/fix-state.js

@@ -0,0 +1,75 @@
+// The GNSS display state machine — bounded acquisition and stale-fix expiry.
+//
+// It exists to make two dishonest renders impossible rather than merely unlikely:
+//
+//   1. An endless "acquiring…" spinner. A modem with no antenna answers "no fix"
+//      forever, quite correctly, and a naive UI waits forever. Acquisition here is
+//      BOUNDED — past `acquireTimeoutMs` the state becomes `no-fix`, which is a
+//      terminal render, not a spinner.
+//   2. A stale coordinate shown as current. A fix is only reachable through
+//      `renderableFix`, which returns one ONLY in the `fix` state; every exit from
+//      that state DROPS the fix rather than carrying it, so there is no code path
+//      that can render a position the modem is no longer reporting.
+//
+// Pure and total: no clock, no I/O. The caller supplies `at` on every event, which
+// is what makes both bounds testable without waiting for real time to pass.
+/**
+ * Defaults chosen against the fleet's own numbers: a cold GNSS start on the
+ * bench modems is a low-minutes affair, so 120 s is long enough to be a fair
+ * attempt and short enough that a missing antenna is reported inside a support
+ * call rather than after one. A fix older than 30 s is not "current" on a moving
+ * vehicle, which is the only context this display has.
+ */
+export const DEFAULT_FIX_STATE_CONFIG = {
+    acquireTimeoutMs: 120_000,
+    fixTtlMs: 30_000,
+};
+export const GNSS_OFF = { kind: 'off' };
+/** A fix is reachable ONLY here, and only while the state actually holds one. */
+export function renderableFix(state) {
+    return state.kind === 'fix' ? state.fix : undefined;
+}
+/** True while a bounded wait is legitimately in progress — the only spinner state. */
+export function isAcquiring(state) {
+    return state.kind === 'acquiring';
+}
+function expireIfDue(state, at, config) {
+    if (state.kind === 'acquiring' && at - state.since >= config.acquireTimeoutMs) {
+        return { kind: 'no-fix', since: at, reason: 'acquire-timeout' };
+    }
+    if (state.kind === 'fix' && at - state.fix.observedAt >= config.fixTtlMs) {
+        return { kind: 'no-fix', since: at, reason: 'fix-expired' };
+    }
+    return state;
+}
+function applyRead(state, at, read, config) {
+    switch (read.outcome) {
+        case 'fix':
+            return { kind: 'fix', fix: read.fix };
+        case 'no-fix':
+            // Still inside the bound, the modem simply has not acquired yet — that is
+            // what `acquiring` means, so a report of no-fix does not end the wait. Any
+            // other state (including a held fix) drops to an honest `no-fix`.
+            return state.kind === 'acquiring'
+                ? expireIfDue(state, at, config)
+                : { kind: 'no-fix', since: at, reason: 'reported-no-fix' };
+        case 'disabled':
+            return GNSS_OFF;
+        case 'unsupported':
+        case 'error':
+            return { kind: 'unavailable', reason: read.reason };
+    }
+}
+/** Pure, total transition. Every exit from `fix` drops the coordinates. */
+export function advanceGnssFixState(state, event, config = DEFAULT_FIX_STATE_CONFIG) {
+    switch (event.kind) {
+        case 'gnss-enabled':
+            return state.kind === 'fix' ? state : { kind: 'acquiring', since: event.at };
+        case 'gnss-disabled':
+            return GNSS_OFF;
+        case 'read':
+            return applyRead(state, event.at, event.read, config);
+        case 'tick':
+            return expireIfDue(state, event.at, config);
+    }
+}

package/dist/location/index.d.ts

@@ -0,0 +1,2 @@
+export * from './fix-state.js';
+export * from './nmea.js';

package/dist/location/index.js

@@ -0,0 +1,8 @@
+// The GPS/location module — the GNSS display state machine and NMEA decoding.
+//
+// PRIVACY FENCE (a product rule, not a phase limitation): this module reads the
+// CURRENT fix and holds it in memory for a live display. There is no history, no
+// track log, no persistence, and no upload — and none may be added here. The port
+// contract in `../ports/location.ts` is guarded by `location-fence.test.ts`.
+export * from './fix-state.js';
+export * from './nmea.js';

package/dist/location/nmea.d.ts

@@ -0,0 +1,10 @@
+export interface NmeaFix {
+    readonly latitude: number;
+    readonly longitude: number;
+    readonly altitude?: number;
+}
+/**
+ * The LAST valid GGA fix in a block of sentences, or `undefined` when none of them
+ * carries one. Never throws — a truncated or corrupt blob is simply not a fix.
+ */
+export declare function parseNmeaFix(text: string): NmeaFix | undefined;

package/dist/location/nmea.js

@@ -0,0 +1,89 @@
+// Minimal NMEA decoding — GGA only, checksum-verified.
+//
+// It exists because `gps-nmea` is the one GNSS source EVERY GNSS-capable modem on
+// the fleet advertises, while `gps-raw` (MM's pre-decoded dict) is not guaranteed:
+// a `gps-unmanaged`-style device hands over sentences and nothing else. Without this
+// the module would have to answer "no fix" to a modem that is reporting one, which
+// is exactly the dishonesty the rest of this module is built to avoid.
+//
+// GGA is the only sentence read: it is the only standard sentence carrying fix
+// QUALITY alongside the position, so "the receiver has not locked on" is decodable
+// rather than inferred. RMC's A/V validity flag would do, but no fleet modem emits
+// RMC without also emitting GGA.
+/** XOR of every character between `$` and `*` — the NMEA checksum. */
+function checksumOf(body) {
+    let sum = 0;
+    for (let i = 0; i < body.length; i += 1) {
+        sum ^= body.charCodeAt(i);
+    }
+    return sum;
+}
+function verifiedBody(sentence) {
+    const trimmed = sentence.trim();
+    if (!trimmed.startsWith('$')) {
+        return undefined;
+    }
+    const star = trimmed.lastIndexOf('*');
+    if (star < 0) {
+        return undefined;
+    }
+    const body = trimmed.slice(1, star);
+    const declared = Number.parseInt(trimmed.slice(star + 1, star + 3), 16);
+    return Number.isNaN(declared) || checksumOf(body) !== declared ? undefined : body;
+}
+/** `ddmm.mmmm` + hemisphere → signed degrees. `degreeDigits` is 2 for lat, 3 for lon. */
+function toDegrees(value, hemisphere, degreeDigits) {
+    if (value.length < degreeDigits + 1) {
+        return undefined;
+    }
+    const degrees = Number.parseFloat(value.slice(0, degreeDigits));
+    const minutes = Number.parseFloat(value.slice(degreeDigits));
+    if (!Number.isFinite(degrees) || !Number.isFinite(minutes)) {
+        return undefined;
+    }
+    const magnitude = degrees + minutes / 60;
+    const negative = hemisphere === 'S' || hemisphere === 'W';
+    return negative ? -magnitude : magnitude;
+}
+function parseGga(fields) {
+    const quality = Number.parseInt(fields[6] ?? '', 10);
+    // Quality 0 is "fix not available". A receiver that is searching emits GGA with
+    // empty position fields and quality 0, so this is the honest no-fix signal.
+    if (!Number.isFinite(quality) || quality <= 0) {
+        return undefined;
+    }
+    const latitude = toDegrees(fields[2] ?? '', fields[3] ?? '', 2);
+    const longitude = toDegrees(fields[4] ?? '', fields[5] ?? '', 3);
+    if (latitude === undefined || longitude === undefined) {
+        return undefined;
+    }
+    if (Math.abs(latitude) > 90 || Math.abs(longitude) > 180) {
+        return undefined;
+    }
+    const altitude = Number.parseFloat(fields[9] ?? '');
+    return {
+        latitude,
+        longitude,
+        ...(Number.isFinite(altitude) ? { altitude } : {}),
+    };
+}
+/**
+ * The LAST valid GGA fix in a block of sentences, or `undefined` when none of them
+ * carries one. Never throws — a truncated or corrupt blob is simply not a fix.
+ */
+export function parseNmeaFix(text) {
+    let latest;
+    for (const line of text.split(/[\r\n]+/)) {
+        const body = verifiedBody(line);
+        if (body === undefined) {
+            continue;
+        }
+        const fields = body.split(',');
+        const type = fields[0] ?? '';
+        if (type.length !== 5 || !type.endsWith('GGA')) {
+            continue;
+        }
+        latest = parseGga(fields) ?? latest;
+    }
+    return latest;
+}

package/dist/observations/envelope.d.ts

@@ -0,0 +1,63 @@
+import type { DeviceGeneration, EpochMillis, ObservationAuthority, ObservationEnvelope, ObservationFreshness, SourceEpoch, StableKey } from '../domain/index.js';
+import type { MetricProvenance, ObservationSourceKind } from './provenance.js';
+export type ObservationStaleReason = Extract<ObservationFreshness, {
+    state: 'stale';
+}>['reason'];
+export type ObservationUnavailableReason = Extract<ObservationFreshness, {
+    state: 'unavailable';
+}>['reason'];
+export type EnvelopeView<T> = {
+    readonly kind: 'valued';
+    readonly value: T;
+    readonly freshness: Extract<ObservationFreshness, {
+        state: 'fresh' | 'stale';
+    }>;
+} | {
+    readonly kind: 'unavailable';
+    readonly freshness: Extract<ObservationFreshness, {
+        state: 'unavailable';
+    }>;
+};
+/**
+ * Split an envelope into its two representable shapes.
+ *
+ * The package's only cast over an envelope lives here. `ObservationEnvelope<T>` pairs
+ * `value: T` with fresh|stale and `value: null` with unavailable BY CONSTRUCTION, but
+ * the discriminant sits one level down (`freshness.state`) and TypeScript narrows a
+ * union only on a direct property — so the pairing the type already guarantees has to
+ * be restated once, here, instead of at every call site.
+ */
+export declare function viewEnvelope<T>(envelope: ObservationEnvelope<T>): EnvelopeView<T>;
+/**
+ * Everything a normalizer needs that it cannot derive from the payload.
+ *
+ * There is no clock and no epoch counter in this layer: `observedAt` and
+ * `sourceEpoch` are supplied by whoever performed the read, so a normalizer cannot
+ * stamp a payload with a time it did not come from.
+ */
+export type NormalizationContext = {
+    readonly stableKey: StableKey;
+    readonly generation: DeviceGeneration;
+    readonly sourceEpoch: SourceEpoch;
+    readonly observedAt: EpochMillis;
+    readonly authority?: ObservationAuthority;
+};
+export declare function contextAuthority(context: NormalizationContext): ObservationAuthority;
+/**
+ * Provenance for one metric.
+ *
+ * `authority` is per-METRIC rather than inherited wholesale, because one payload can
+ * mix classes: a router's RSRP is a measurement the modem reported, while its bar
+ * count is a vendor rendering of that measurement, and calling both `authoritative`
+ * would let a consumer treat a marketing scale as a reading.
+ */
+export declare function metricProvenance(source: ObservationSourceKind, context: NormalizationContext, rawFields: readonly string[], authority?: ObservationAuthority): MetricProvenance;
+/** A fresh envelope around a normalized value. */
+export declare function freshObservation<T>(source: ObservationSourceKind, context: NormalizationContext, value: T): ObservationEnvelope<T>;
+/**
+ * An envelope for a read that produced no payload at all.
+ *
+ * It carries `value: null` by construction — there is no overload that could invent
+ * one — which is also why a normalizer holding vendor bytes must not use it.
+ */
+export declare function unavailableObservation<T>(source: ObservationSourceKind, context: NormalizationContext, reason: ObservationUnavailableReason): ObservationEnvelope<T>;

package/dist/observations/envelope.js

@@ -0,0 +1,77 @@
+// Envelope construction for normalizers.
+//
+// One rule shapes this module: **a payload that arrived is an OBSERVATION, however
+// little of it could be read.** A refused HiLink session, an unparseable goform body
+// and a UFI endpoint that answered without the field all produce a FRESH envelope
+// whose metrics are `unknown` with a reason — not an `unavailable` one. That matters
+// for a reason beyond taxonomy: `ObservationEnvelope` pairs `unavailable` with
+// `value: null`, so emitting `unavailable` for a payload we did hold would throw the
+// diagnostics block away with it, and the raw vendor fields with that.
+//
+// `unavailable` is therefore reserved for the case where there is no payload at all —
+// the device is gone, or the provider could not be engaged.
+/**
+ * Split an envelope into its two representable shapes.
+ *
+ * The package's only cast over an envelope lives here. `ObservationEnvelope<T>` pairs
+ * `value: T` with fresh|stale and `value: null` with unavailable BY CONSTRUCTION, but
+ * the discriminant sits one level down (`freshness.state`) and TypeScript narrows a
+ * union only on a direct property — so the pairing the type already guarantees has to
+ * be restated once, here, instead of at every call site.
+ */
+export function viewEnvelope(envelope) {
+    return envelope.freshness.state === 'unavailable'
+        ? { kind: 'unavailable', freshness: envelope.freshness }
+        : { kind: 'valued', value: envelope.value, freshness: envelope.freshness };
+}
+export function contextAuthority(context) {
+    return context.authority ?? 'authoritative';
+}
+/**
+ * Provenance for one metric.
+ *
+ * `authority` is per-METRIC rather than inherited wholesale, because one payload can
+ * mix classes: a router's RSRP is a measurement the modem reported, while its bar
+ * count is a vendor rendering of that measurement, and calling both `authoritative`
+ * would let a consumer treat a marketing scale as a reading.
+ */
+export function metricProvenance(source, context, rawFields, authority) {
+    return {
+        source,
+        sourceEpoch: context.sourceEpoch,
+        observedAt: context.observedAt,
+        authority: authority ?? contextAuthority(context),
+        rawFields,
+    };
+}
+/** A fresh envelope around a normalized value. */
+export function freshObservation(source, context, value) {
+    return {
+        stableKey: context.stableKey,
+        generation: context.generation,
+        source,
+        sourceEpoch: context.sourceEpoch,
+        observedAt: context.observedAt,
+        authority: contextAuthority(context),
+        freshness: { state: 'fresh' },
+        value,
+    };
+}
+/**
+ * An envelope for a read that produced no payload at all.
+ *
+ * It carries `value: null` by construction — there is no overload that could invent
+ * one — which is also why a normalizer holding vendor bytes must not use it.
+ */
+export function unavailableObservation(source, context, reason) {
+    return {
+        stableKey: context.stableKey,
+        generation: context.generation,
+        source,
+        sourceEpoch: context.sourceEpoch,
+        observedAt: context.observedAt,
+        authority: contextAuthority(context),
+        freshness: { state: 'unavailable', since: context.observedAt, reason },
+        value: null,
+    };
+}

package/dist/observations/freshness.d.ts

@@ -0,0 +1,28 @@
+import { type DeviceGeneration, type EpochMillis, type ObservationEnvelope, type SourceEpoch } from '../domain/index.js';
+/** How long a retained value is reported fresh before it ages into `stale`. */
+export type FreshnessWindow = {
+    readonly ttlMs: number;
+};
+export type FreshnessEvaluation = {
+    /** The caller's current time. This module never reads a clock of its own. */
+    readonly at: EpochMillis;
+    readonly window: FreshnessWindow;
+    /** The source's current epoch; an older envelope epoch is superseded. */
+    readonly currentSourceEpoch?: SourceEpoch;
+    /** The device's current generation; an envelope from an older one is fenced out. */
+    readonly currentGeneration?: DeviceGeneration;
+    /** `false` marks a source that is answering but degraded (e.g. a reconnecting bus). */
+    readonly sourceHealthy?: boolean;
+};
+/** How long ago an envelope was observed, floored at zero for a clock that moved back. */
+export declare function observationAgeMs<T>(envelope: ObservationEnvelope<T>, at: EpochMillis): number;
+/**
+ * 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 declare function evaluateFreshness<T>(envelope: ObservationEnvelope<T>, evaluation: FreshnessEvaluation): ObservationEnvelope<T>;

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,47 @@
+import type { RouterSignalMetric, RouterSignalUnknownReason } from '../hardware/router-parsers.js';
+import type { MetricProvenance } from './provenance.js';
+export declare const METRIC_UNKNOWN_REASONS: readonly ["unsupported", "not-reported", "not-observed", "malformed", "auth-expired", "refused", "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);
+}