@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/journal/store.d.ts

@@ -0,0 +1,55 @@
+import { type JournalDecodeFailure } from './codec.js';
+import type { JournalEntry } from './entry.js';
+/** Default file mode. `0600` for the same reason the two policy stores use it. */
+export declare const JOURNAL_FILE_MODE = 384;
+/** Where a damaged record was found. Line-based, slot-based, or the whole file. */
+export type JournalDamageLocation = {
+    readonly kind: 'line';
+    readonly line: number;
+    readonly trailing: boolean;
+} | {
+    readonly kind: 'slot';
+    readonly slot: string;
+} | {
+    readonly kind: 'file';
+};
+/** One record that could not be read, reported rather than dropped. */
+export interface JournalDamageRecord {
+    readonly location: JournalDamageLocation;
+    readonly bytes: number;
+    readonly failure: JournalDecodeFailure;
+}
+/** One decoded entry with the 1-based line it came from. */
+export interface JournalLineRecord {
+    readonly line: number;
+    readonly entry: JournalEntry;
+}
+export interface JournalReadResult {
+    readonly entries: readonly JournalLineRecord[];
+    readonly damage: readonly JournalDamageRecord[];
+}
+export interface JournalStore {
+    /** The injected path, echoed back so a caller can report where it recovered from. */
+    readonly path: string;
+    append(entry: JournalEntry): Promise<void>;
+    read(): Promise<JournalReadResult>;
+}
+export interface FileJournalStoreOptions {
+    /** REQUIRED. There is no default and no fallback. */
+    readonly path: string;
+    readonly mode?: number;
+}
+export declare class JournalPathError extends Error {
+    readonly name = "JournalPathError";
+    constructor();
+}
+/**
+ * Decode a whole journal document.
+ *
+ * Exported because the corruption fixtures assert against it directly — proving
+ * the "survivors are kept" property without needing a filesystem to prove it.
+ * Blank lines carry no record and are skipped rather than reported: a trailing
+ * newline is how every line ends, so the final split member is always empty.
+ */
+export declare function decodeJournalText(text: string): JournalReadResult;
+export declare function createFileJournalStore(options: FileJournalStoreOptions): JournalStore;

package/dist/journal/store.js

@@ -0,0 +1,150 @@
+// The append-only journal store. THE PATH IS INJECTED AND HAS NO DEFAULT.
+//
+// This package never learns where a journal lives. The embedding process owns that
+// decision because it owns the filesystem contract: on a CeraLive device the
+// update-surviving partition is the right home, on a bench box a scratch directory
+// is, and in a test a `mkdtemp` directory is. A default here would be a policy this
+// library has no standing to set, and — worse — a default is what turns "the
+// embedder forgot to configure it" into "we silently wrote somewhere plausible".
+// `journal-path-injection.test.ts` fails the build if an absolute path literal ever
+// appears in this directory's executable source.
+//
+// THREE PROPERTIES THIS STORE GUARANTEES, ALL LOAD-BEARING:
+//
+//  1. APPEND-ONLY. There is no verb here that rewrites or truncates the file.
+//     A rewrite is the one operation that can lose a fact that was already
+//     durable, and a journal that can lose a fact answers nothing after a crash.
+//
+//  2. A DAMAGED RECORD NEVER DISCARDS ITS NEIGHBOURS. `read()` decodes every line
+//     independently and returns the survivors alongside a typed damage report.
+//     Stopping at the first bad line — the natural thing a `for` loop with a throw
+//     does — silently truncates the journal to its first corruption, which is
+//     exactly the failure mode this store exists to make impossible.
+//
+//  3. A TORN TRAILING LINE IS CLOSED BEFORE THE NEXT APPEND. A process killed
+//     mid-write leaves a final line with no terminator. Appending straight onto it
+//     would glue the new entry to the garbage and corrupt a SECOND record — one
+//     that was never in flight when the crash happened. The store probes the last
+//     byte once and emits a leading terminator when the file does not end in one,
+//     so the damage stays confined to the record that actually tore.
+import { appendFile, chmod, mkdir, open, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { decodeJournalEntry, encodeJournalEntry } from './codec.js';
+const NEWLINE = 0x0a;
+/** Default file mode. `0600` for the same reason the two policy stores use it. */
+export const JOURNAL_FILE_MODE = 0o600;
+export class JournalPathError extends Error {
+    name = 'JournalPathError';
+    constructor() {
+        super('journal path refused: an explicit, non-empty path must be injected');
+    }
+}
+/**
+ * Decode a whole journal document.
+ *
+ * Exported because the corruption fixtures assert against it directly — proving
+ * the "survivors are kept" property without needing a filesystem to prove it.
+ * Blank lines carry no record and are skipped rather than reported: a trailing
+ * newline is how every line ends, so the final split member is always empty.
+ */
+export function decodeJournalText(text) {
+    const lines = text.split('\n');
+    let lastPopulated = -1;
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        if ((lines[index] ?? '').trim().length > 0) {
+            lastPopulated = index;
+            break;
+        }
+    }
+    const entries = [];
+    const damage = [];
+    for (const [index, raw] of lines.entries()) {
+        if (raw.trim().length === 0)
+            continue;
+        const decoded = decodeJournalEntry(raw);
+        if (decoded.ok) {
+            entries.push({ line: index + 1, entry: decoded.value });
+            continue;
+        }
+        damage.push({
+            location: { kind: 'line', line: index + 1, trailing: index === lastPopulated },
+            bytes: Buffer.byteLength(raw, 'utf8'),
+            failure: decoded.failure,
+        });
+    }
+    return { entries, damage };
+}
+class FileJournalStore {
+    path;
+    #mode;
+    #tail = Promise.resolve();
+    /** Undefined until the first append probes the existing file's final byte. */
+    #terminated;
+    constructor(options) {
+        if (typeof options.path !== 'string' || options.path.trim().length === 0) {
+            throw new JournalPathError();
+        }
+        this.path = options.path;
+        this.#mode = options.mode ?? JOURNAL_FILE_MODE;
+    }
+    append(entry) {
+        // Chained so two concurrent appends cannot interleave, and recovered from so
+        // one failed append does not poison every later one with its rejection.
+        const next = this.#tail.catch(() => undefined).then(() => this.#appendNow(entry));
+        this.#tail = next.catch(() => undefined);
+        return next;
+    }
+    async read() {
+        let text;
+        try {
+            text = await readFile(this.path, 'utf8');
+        }
+        catch (error) {
+            // An ABSENT journal is an empty one — nothing was ever written. Anything
+            // else (permissions, a directory in the way) is reported as damage: a
+            // journal we could not open is not evidence that no mutation was pending.
+            if (error.code === 'ENOENT') {
+                return { entries: [], damage: [] };
+            }
+            return {
+                entries: [],
+                damage: [{ location: { kind: 'file' }, bytes: 0, failure: { code: 'unreadable' } }],
+            };
+        }
+        return decodeJournalText(text);
+    }
+    async #appendNow(entry) {
+        await mkdir(dirname(this.path), { recursive: true });
+        this.#terminated ??= await this.#probeTerminated();
+        const line = `${this.#terminated ? '' : '\n'}${encodeJournalEntry(entry)}\n`;
+        await appendFile(this.path, line, { mode: this.#mode });
+        // chmod AFTER the write, not as an open flag, so the mode holds regardless of
+        // umask — the same reason the usage and FCC policy stores do it this way.
+        await chmod(this.path, this.#mode);
+        this.#terminated = true;
+    }
+    async #probeTerminated() {
+        let handle;
+        try {
+            handle = await open(this.path, 'r');
+        }
+        catch {
+            // No file yet: the first line starts the document, nothing to close.
+            return true;
+        }
+        try {
+            const { size } = await handle.stat();
+            if (size === 0)
+                return true;
+            const tail = Buffer.alloc(1);
+            await handle.read(tail, 0, 1, size - 1);
+            return tail[0] === NEWLINE;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+export function createFileJournalStore(options) {
+    return new FileJournalStore(options);
+}

package/dist/location/fix-state.d.ts

@@ -0,0 +1,53 @@
+import type { EpochMillis } from '../domain/index.js';
+import type { FixRead, GnssFix } from '../ports/location.js';
+export interface GnssFixStateConfig {
+    /** How long acquisition may run before the state turns to an honest `no-fix`. */
+    readonly acquireTimeoutMs: number;
+    /** How long a fix stays current before it expires and is dropped. */
+    readonly fixTtlMs: number;
+}
+/**
+ * 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 declare const DEFAULT_FIX_STATE_CONFIG: GnssFixStateConfig;
+export type NoFixReason = 'acquire-timeout' | 'reported-no-fix' | 'fix-expired';
+export type GnssFixState = {
+    readonly kind: 'off';
+} | {
+    readonly kind: 'acquiring';
+    readonly since: EpochMillis;
+} | {
+    readonly kind: 'no-fix';
+    readonly since: EpochMillis;
+    readonly reason: NoFixReason;
+} | {
+    readonly kind: 'fix';
+    readonly fix: GnssFix;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+export type GnssFixEvent = {
+    readonly kind: 'gnss-enabled';
+    readonly at: EpochMillis;
+} | {
+    readonly kind: 'gnss-disabled';
+} | {
+    readonly kind: 'read';
+    readonly at: EpochMillis;
+    readonly read: FixRead;
+} | {
+    readonly kind: 'tick';
+    readonly at: EpochMillis;
+};
+export declare const GNSS_OFF: GnssFixState;
+/** A fix is reachable ONLY here, and only while the state actually holds one. */
+export declare function renderableFix(state: GnssFixState): GnssFix | undefined;
+/** True while a bounded wait is legitimately in progress — the only spinner state. */
+export declare function isAcquiring(state: GnssFixState): boolean;
+/** Pure, total transition. Every exit from `fix` drops the coordinates. */
+export declare function advanceGnssFixState(state: GnssFixState, event: GnssFixEvent, config?: GnssFixStateConfig): GnssFixState;

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>;