@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/domain/guards.js

@@ -0,0 +1,127 @@
+// Impossible-combination guards.
+//
+// The orthogonal dimensions are independent, but not EVERY combination is
+// physically real. A modem cannot be `registered` while `absent`; the radio
+// cannot be `off` while the modem is `connected`. Each rule below rejects one
+// such impossible cross-dimension combination with a distinct code, so a bad
+// construction names exactly what it violated instead of silently persisting an
+// incoherent snapshot. `checkSnapshot` returns the first violation (or null);
+// `assertSnapshot` throws `ImpossibleStateError`.
+import { ImpossibleStateError } from './errors.js';
+import { isRegistered, MM_STATES_REQUIRING_RADIO, SIM_LOCK_REQUIRES_CARD } from './state.js';
+function checkRegistration(s) {
+    if (!isRegistered(s.registration.status)) {
+        return null;
+    }
+    if (s.presence === 'absent') {
+        return { code: 'registered-while-absent', detail: `status=${s.registration.status}` };
+    }
+    if (s.radioPower === 'off') {
+        return { code: 'registered-radio-off', detail: `status=${s.registration.status}` };
+    }
+    if (s.registration.activeRats.size === 0) {
+        return { code: 'registered-empty-rat-set', detail: `status=${s.registration.status}` };
+    }
+    return null;
+}
+function radioIsOnTheAir(s) {
+    return (MM_STATES_REQUIRING_RADIO.has(s.mmState) ||
+        s.registration.status === 'searching' ||
+        s.nmActivation === 'activating' ||
+        s.nmActivation === 'activated');
+}
+function checkRadioAndPresence(s) {
+    if (MM_STATES_REQUIRING_RADIO.has(s.mmState) && s.presence === 'absent') {
+        return { code: 'active-state-while-absent', detail: `mmState=${s.mmState}` };
+    }
+    if (s.radioPower === 'off' && radioIsOnTheAir(s)) {
+        return { code: 'radio-off-while-active', detail: `mmState=${s.mmState}` };
+    }
+    return null;
+}
+function checkNmActivation(s) {
+    if (s.nmActivation !== 'activated') {
+        return null;
+    }
+    if (s.presence === 'absent') {
+        return { code: 'nm-activated-while-absent', detail: 'nmActivation=activated' };
+    }
+    if (!s.dataInterface.present) {
+        return { code: 'nm-activated-without-interface', detail: 'nmActivation=activated' };
+    }
+    if (s.mmState !== 'connected') {
+        return { code: 'nm-activated-without-mm-connected', detail: `mmState=${s.mmState}` };
+    }
+    return null;
+}
+function checkSimSlots(s) {
+    let activeCount = 0;
+    let hasLockedCard = false;
+    for (const slot of s.simSlots) {
+        if (slot.active) {
+            activeCount += 1;
+        }
+        if (!slot.occupied && SIM_LOCK_REQUIRES_CARD.has(slot.lock)) {
+            return { code: 'locked-sim-in-empty-slot', detail: `slot=${slot.index} lock=${slot.lock}` };
+        }
+        if (slot.occupied && SIM_LOCK_REQUIRES_CARD.has(slot.lock)) {
+            hasLockedCard = true;
+        }
+    }
+    if (activeCount > 1) {
+        return { code: 'multiple-active-sim-slots', detail: `active=${activeCount}` };
+    }
+    if (s.mmState === 'locked' && !hasLockedCard) {
+        return { code: 'mm-locked-without-sim-lock', detail: 'mmState=locked' };
+    }
+    return null;
+}
+function checkDataInterface(s) {
+    if (!s.dataInterface.present && s.dataInterface.name !== undefined) {
+        return {
+            code: 'data-interface-name-without-presence',
+            detail: `name=${s.dataInterface.name}`,
+        };
+    }
+    return null;
+}
+function checkRecovery(s) {
+    const { stage, attempts, cooldownUntil } = s.recoveryState;
+    if (!Number.isSafeInteger(attempts) || attempts < 0) {
+        return { code: 'recovery-attempts-negative', detail: `attempts=${attempts}` };
+    }
+    if ((cooldownUntil !== undefined) !== (stage === 'cooldown')) {
+        return { code: 'recovery-cooldown-stage-mismatch', detail: `stage=${stage}` };
+    }
+    if (stage === 'idle' && attempts !== 0) {
+        return { code: 'recovery-idle-with-attempts', detail: `attempts=${attempts}` };
+    }
+    return null;
+}
+const CHECKS = [
+    checkRegistration,
+    checkRadioAndPresence,
+    checkNmActivation,
+    checkSimSlots,
+    checkDataInterface,
+    checkRecovery,
+];
+/** Return the first impossible-combination code the snapshot violates, or null. */
+export function checkSnapshot(snapshot) {
+    for (const check of CHECKS) {
+        const violation = check(snapshot);
+        if (violation !== null) {
+            return violation.code;
+        }
+    }
+    return null;
+}
+/** Throw `ImpossibleStateError` if the snapshot holds an impossible combination. */
+export function assertSnapshot(snapshot) {
+    for (const check of CHECKS) {
+        const violation = check(snapshot);
+        if (violation !== null) {
+            throw new ImpossibleStateError(violation.code, violation.detail);
+        }
+    }
+}

package/dist/domain/identity.d.ts

@@ -0,0 +1,109 @@
+import type { Brand } from './brand.js';
+/**
+ * Stable physical-slot handle (e.g. `slot-usb-1-2`). The ONLY id durable policy
+ * and routing are allowed to bind to — it survives equipment swaps in the slot.
+ */
+export type LogicalSlotId = Brand<string, 'LogicalSlotId'>;
+/**
+ * SIM subscription id (ICCID or EID).
+ *
+ * SENSITIVE — this value identifies a subscriber. It MUST be redacted in every
+ * log, telemetry, and error surface (the redaction module lands in A2.2). Treat
+ * it as PII: never print it raw, never include it in a policy binding key.
+ */
+export type SubscriptionId = Brand<string, 'SubscriptionId'>;
+/**
+ * The SIM's OWN number (MSISDN), as ModemManager's `Modem.OwnNumbers` reports it.
+ *
+ * SENSITIVE — it is the subscriber's telephone number, so it belongs to the same
+ * class as `subscriptionId`: never printed raw, never a policy binding key. It is
+ * DISPLAYED to the operator on an explicit reveal; that is a rendering decision
+ * and does not make it loggable.
+ */
+export type SubscriberNumber = Brand<string, 'SubscriberNumber'>;
+/**
+ * The live ModemManager D-Bus object path (e.g. `/org/freedesktop/ModemManager1/Modem/3`).
+ *
+ * NEVER PERSISTED — this is a per-boot runtime handle. ModemManager reassigns it
+ * across daemon restarts and device replug, so it is meaningless in durable
+ * storage. Durable keys derive from `logicalSlotId`/`equipmentId` only; storage
+ * code in later waves must never write this field. The type name and this note
+ * make that intent unambiguous at the domain layer.
+ */
+export type RuntimePath = Brand<string, 'RuntimePath'>;
+/** How the equipment id was obtained. Discriminated union over the source. */
+export type EquipmentProvenance = 'imei' | 'serial' | 'none';
+/**
+ * Trust in the equipment id as a durable key.
+ *
+ *   - high   — a well-formed, unique IMEI.
+ *   - medium — a serial fallback, or an IMEI of non-standard shape.
+ *   - low    — AMBIGUOUS: a zero/blank IMEI, or a value seen on more than one
+ *              modem (duplicate). A low-confidence identity must NEVER bind
+ *              durable policy — see `policyBindingKey` / `canBindPolicy`.
+ */
+export type IdentityConfidence = 'high' | 'medium' | 'low';
+/**
+ * The equipment id, discriminated on `provenance`.
+ *
+ * `imei` and `serial` carry a `value`; `none` carries none — we genuinely have no
+ * equipment identifier, so `value` would be a lie. `none` is always low confidence.
+ */
+export type EquipmentId = {
+    readonly provenance: 'imei';
+    readonly value: string;
+    readonly confidence: IdentityConfidence;
+} | {
+    readonly provenance: 'serial';
+    readonly value: string;
+    readonly confidence: IdentityConfidence;
+} | {
+    readonly provenance: 'none';
+    readonly confidence: 'low';
+};
+/** The four-part modem identity. */
+export interface ModemIdentity {
+    /** Absent until the identity ladder resolves a physical slot. */
+    readonly logicalSlotId?: LogicalSlotId;
+    readonly equipmentId: EquipmentId;
+    /** Absent with no SIM. SENSITIVE — redact everywhere (A2.2 redaction module). */
+    readonly subscriptionId?: SubscriptionId;
+    /**
+     * The SIM's own number(s). ABSENT when the carrier/SIM published none — most
+     * SIMs do not, so absence is the common case and never an error. SENSITIVE.
+     */
+    readonly ownNumbers?: readonly SubscriberNumber[];
+    /** NEVER PERSISTED — per-boot runtime handle only. */
+    readonly runtimePath: RuntimePath;
+}
+/** Construct a `LogicalSlotId` from a non-empty string. */
+export declare function logicalSlotId(value: string): LogicalSlotId;
+/** Construct a `SubscriptionId` from a non-empty string. */
+export declare function subscriptionId(value: string): SubscriptionId;
+/** Construct a `SubscriberNumber` from a non-empty string. */
+export declare function subscriberNumber(value: string): SubscriberNumber;
+/** Construct a `RuntimePath` from a non-empty string. */
+export declare function runtimePath(value: string): RuntimePath;
+/** The absence of any equipment id — always low confidence. */
+export declare const NO_EQUIPMENT_ID: EquipmentId;
+/** Build an IMEI-provenance equipment id, grading confidence from the value. */
+export declare function imeiEquipmentId(value: string): EquipmentId;
+/**
+ * Build a serial-fallback equipment id. A serial is never as trustworthy as a
+ * clean IMEI, so it caps at `medium` (blank → `low`).
+ */
+export declare function serialEquipmentId(value: string): EquipmentId;
+/**
+ * Demote an equipment id to `low` confidence — used by the identity ladder when a
+ * value turns out to be shared across modems (duplicate IMEI). Idempotent; `none`
+ * is already low.
+ */
+export declare function demoteToLowConfidence(id: EquipmentId): EquipmentId;
+/**
+ * Whether this identity may bind DURABLE policy. False for ambiguous
+ * (low-confidence) equipment identities — a duplicate or zero IMEI must never
+ * become the durable key that a saved policy attaches to.
+ */
+export declare function canBindPolicy(identity: ModemIdentity): boolean;
+/** Throw `PolicyBindingRefusedError` if the identity may not bind durable policy. */
+export declare function assertCanBindPolicy(identity: ModemIdentity): void;

package/dist/domain/identity.js

@@ -0,0 +1,86 @@
+// Modem identity — the four ids that pin a physical modem across its lifecycle.
+//
+// Design (draft §Oracle round-1): a modem is identified by FOUR distinct ids, not
+// one, because each answers a different question and each has a different lifetime:
+//
+//   - logicalSlotId  — the stable physical-slot handle. Durable policy and routing
+//                      bind to THIS. Optional: absent until the identity ladder
+//                      (A3.2) resolves a slot from udev/Physdev/sysfs.
+//   - equipmentId    — IMEI (or serial fallback) with provenance + confidence.
+//   - subscriptionId — ICCID/EID. SENSITIVE (see marker below). Optional: no SIM.
+//   - runtimePath    — the live ModemManager D-Bus object path. NEVER PERSISTED.
+import { nonEmptyString } from './brand.js';
+import { PolicyBindingRefusedError } from './errors.js';
+// --- constructors ----------------------------------------------------------
+/** Construct a `LogicalSlotId` from a non-empty string. */
+export function logicalSlotId(value) {
+    return nonEmptyString(value, 'logicalSlotId');
+}
+/** Construct a `SubscriptionId` from a non-empty string. */
+export function subscriptionId(value) {
+    return nonEmptyString(value, 'subscriptionId');
+}
+/** Construct a `SubscriberNumber` from a non-empty string. */
+export function subscriberNumber(value) {
+    return nonEmptyString(value, 'subscriberNumber');
+}
+/** Construct a `RuntimePath` from a non-empty string. */
+export function runtimePath(value) {
+    return nonEmptyString(value, 'runtimePath');
+}
+const ALL_ZEROS = /^0+$/;
+/**
+ * Grade an IMEI's confidence from its own shape alone.
+ *
+ * A blank or all-zeros IMEI is a well-known ambiguous placeholder → `low`. A
+ * canonical 15/16-digit IMEI → `high`. Anything else → `medium`. DUPLICATE
+ * detection is cross-modem and cannot be done from a single value here; A3.2
+ * demotes duplicates to `low` via `demoteToLowConfidence`.
+ */
+function gradeImei(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || ALL_ZEROS.test(trimmed)) {
+        return 'low';
+    }
+    return /^\d{15,16}$/.test(trimmed) ? 'high' : 'medium';
+}
+/** The absence of any equipment id — always low confidence. */
+export const NO_EQUIPMENT_ID = { provenance: 'none', confidence: 'low' };
+/** Build an IMEI-provenance equipment id, grading confidence from the value. */
+export function imeiEquipmentId(value) {
+    return { provenance: 'imei', value, confidence: gradeImei(value) };
+}
+/**
+ * Build a serial-fallback equipment id. A serial is never as trustworthy as a
+ * clean IMEI, so it caps at `medium` (blank → `low`).
+ */
+export function serialEquipmentId(value) {
+    const confidence = value.trim().length === 0 ? 'low' : 'medium';
+    return { provenance: 'serial', value, confidence };
+}
+/**
+ * Demote an equipment id to `low` confidence — used by the identity ladder when a
+ * value turns out to be shared across modems (duplicate IMEI). Idempotent; `none`
+ * is already low.
+ */
+export function demoteToLowConfidence(id) {
+    if (id.provenance === 'none') {
+        return id;
+    }
+    return { provenance: id.provenance, value: id.value, confidence: 'low' };
+}
+// --- policy-binding gate ----------------------------------------------------
+/**
+ * Whether this identity may bind DURABLE policy. False for ambiguous
+ * (low-confidence) equipment identities — a duplicate or zero IMEI must never
+ * become the durable key that a saved policy attaches to.
+ */
+export function canBindPolicy(identity) {
+    return identity.equipmentId.confidence !== 'low';
+}
+/** Throw `PolicyBindingRefusedError` if the identity may not bind durable policy. */
+export function assertCanBindPolicy(identity) {
+    if (!canBindPolicy(identity)) {
+        throw new PolicyBindingRefusedError(`equipment id (provenance=${identity.equipmentId.provenance}) is low-confidence`);
+    }
+}

package/dist/domain/index.d.ts

@@ -0,0 +1,14 @@
+export * from './brand.js';
+export * from './errors.js';
+export * from './generation.js';
+export * from './guards.js';
+export * from './identity.js';
+export * from './mm-enums.js';
+export * from './modem-presentation.js';
+export * from './observation.js';
+export * from './operation.js';
+export * from './physical-identity.js';
+export * from './policy.js';
+export * from './shadow-divergence.js';
+export * from './snapshot.js';
+export * from './state.js';

package/dist/domain/index.js

@@ -0,0 +1,18 @@
+// Domain layer — pure types + reducers for modem identity and orthogonal state.
+//
+// No I/O, no D-Bus, no NetworkManager: this module is data and pure functions
+// only. Later waves (A2.2 ports, A3.x D-Bus backend) build on these exact shapes.
+export * from './brand.js';
+export * from './errors.js';
+export * from './generation.js';
+export * from './guards.js';
+export * from './identity.js';
+export * from './mm-enums.js';
+export * from './modem-presentation.js';
+export * from './observation.js';
+export * from './operation.js';
+export * from './physical-identity.js';
+export * from './policy.js';
+export * from './shadow-divergence.js';
+export * from './snapshot.js';
+export * from './state.js';

package/dist/domain/mm-enums.d.ts

@@ -0,0 +1,12 @@
+import type { RadioAccessTechnology } from './state.js';
+export declare function decodeMmAccessTechnologies(mask: number | undefined): Set<RadioAccessTechnology>;
+export declare function modeMaskToLabel(mask: number | undefined): string | undefined;
+export declare function decodeMmState(state: number | undefined): string;
+export declare function decodeRegistrationState(state: number | undefined): string;
+export declare function decodeStateFailedReason(value: number | undefined): string | undefined;
+export declare function decodeUnlockRequired(lock: number | undefined): string | undefined;
+export declare function decodeSimType(value: number | undefined): 'physical' | 'esim' | undefined;
+export declare function decodeEsimStatus(value: number | undefined): 'no-profiles' | 'with-profiles' | undefined;
+export declare function decodePacketServiceState(value: number | undefined): 'detached' | 'attached' | undefined;
+export declare function decodeNetworkRejectionError(value: number | undefined): string | undefined;
+export declare function runtimeIdFromPath(path: string): number | undefined;

package/dist/domain/mm-enums.js

@@ -0,0 +1,139 @@
+const ACCESS_TECH_BITS = [
+    [1 << 1, 'gsm'],
+    [1 << 2, 'gsm'],
+    [1 << 3, 'gsm'],
+    [1 << 4, 'gsm'],
+    [1 << 5, 'umts'],
+    [1 << 6, 'umts'],
+    [1 << 7, 'umts'],
+    [1 << 8, 'umts'],
+    [1 << 9, 'umts'],
+    [1 << 14, 'lte'],
+    [1 << 15, '5gnr'],
+    [1 << 16, 'lte'],
+    [1 << 17, 'lte'],
+];
+export function decodeMmAccessTechnologies(mask) {
+    const result = new Set();
+    if (mask === undefined || mask <= 0)
+        return result;
+    for (const [bit, rat] of ACCESS_TECH_BITS)
+        if ((mask & bit) !== 0)
+            result.add(rat);
+    return result;
+}
+export function modeMaskToLabel(mask) {
+    if (mask === undefined || mask <= 0)
+        return undefined;
+    const tokens = [
+        [1 << 1, '2g'],
+        [1 << 2, '3g'],
+        [1 << 3, '4g'],
+        [1 << 4, '5g'],
+    ];
+    const named = tokens.filter(([bit]) => (mask & bit) !== 0).map(([, token]) => token);
+    return named.length === 0 ? undefined : named.reverse().join('');
+}
+const MM_STATES = new Map([
+    [-1, 'failed'],
+    [1, 'initializing'],
+    [2, 'locked'],
+    [3, 'disabled'],
+    [4, 'disabling'],
+    [5, 'enabling'],
+    [6, 'enabled'],
+    [7, 'searching'],
+    [8, 'registered'],
+    [9, 'disconnecting'],
+    [10, 'connecting'],
+    [11, 'connected'],
+]);
+export function decodeMmState(state) {
+    return state === undefined ? 'unknown' : (MM_STATES.get(state) ?? 'unknown');
+}
+export function decodeRegistrationState(state) {
+    if (state === 0)
+        return 'idle';
+    if (state === 1 || state === 6 || state === 7)
+        return 'home';
+    if (state === 2)
+        return 'searching';
+    if (state === 3)
+        return 'denied';
+    if (state === 5 || state === 8 || state === 9)
+        return 'roaming';
+    return state === 11 ? 'emergency-only' : 'unknown';
+}
+/**
+ * `MMModemStateFailedReason` → its mmcli spelling.
+ *
+ * This decoder is what makes "there is no SIM" an EXPLICIT reading rather than an
+ * inference. `Modem.StateFailedReason` is a `u` on D-Bus, so a provider that copies
+ * the property verbatim holds a NUMBER, while the migrated SIM-presence rule
+ * (`deriveSimPresence`) matches the mmcli STRING `sim-missing` that CeraUI has always
+ * read. Without this decoder the D-Bus path can never produce the one fact that
+ * proves absence, and a modem with no SIM reads `unknown` forever — or, worse,
+ * invites a consumer to infer absence from the blank `Sim` object path, which is
+ * exactly the guess this package refuses to make.
+ *
+ * An unrecognized value answers `undefined`: a reason this build cannot place says
+ * nothing, and must not be laundered into one that does.
+ */
+const STATE_FAILED_REASONS = new Map([
+    [0, 'none'],
+    // MM's own `UNKNOWN` member. Spelled distinctly so it is never confused with the
+    // `'unknown'` sentinel the label decoders use to mean "this build could not place it".
+    [1, 'unknown-reason'],
+    [2, 'sim-missing'],
+    [3, 'sim-error'],
+    [4, 'unknown-capabilities'],
+    [5, 'esim-without-profiles'],
+]);
+export function decodeStateFailedReason(value) {
+    return value === undefined ? undefined : STATE_FAILED_REASONS.get(value);
+}
+export function decodeUnlockRequired(lock) {
+    return lock === 1
+        ? 'none'
+        : lock === 2
+            ? 'sim-pin'
+            : lock === 3
+                ? 'sim-pin2'
+                : lock === 4
+                    ? 'sim-puk'
+                    : lock === 5
+                        ? 'sim-puk2'
+                        : undefined;
+}
+export function decodeSimType(value) {
+    return value === 1 ? 'physical' : value === 2 ? 'esim' : undefined;
+}
+export function decodeEsimStatus(value) {
+    return value === 1 ? 'no-profiles' : value === 2 ? 'with-profiles' : undefined;
+}
+export function decodePacketServiceState(value) {
+    return value === 1 ? 'detached' : value === 2 ? 'attached' : undefined;
+}
+const NETWORK_REJECTIONS = new Map([
+    [2, 'imsi-unknown-in-hlr'],
+    [3, 'illegal-ms'],
+    [4, 'imsi-unknown-in-vlr'],
+    [5, 'imei-not-accepted'],
+    [6, 'illegal-me'],
+    [7, 'gprs-not-allowed'],
+    [8, 'gprs-and-non-gprs-not-allowed'],
+    [11, 'plmn-not-allowed'],
+    [12, 'location-area-not-allowed'],
+    [13, 'roaming-not-allowed-in-location-area'],
+    [14, 'gprs-not-allowed-in-plmn'],
+    [15, 'no-cells-in-location-area'],
+    [17, 'network-failure'],
+    [22, 'congestion'],
+]);
+export function decodeNetworkRejectionError(value) {
+    return value === undefined ? undefined : NETWORK_REJECTIONS.get(value);
+}
+export function runtimeIdFromPath(path) {
+    const value = /\/(\d+)$/.exec(path)?.[1];
+    return value === undefined ? undefined : Number.parseInt(value, 10);
+}

package/dist/domain/modem-presentation.d.ts

@@ -0,0 +1,10 @@
+export interface ModemHardwareIdentity {
+    readonly model?: string;
+    readonly manufacturer?: string;
+    readonly firmwareRevision?: string;
+    readonly equipmentId?: string;
+}
+export declare function isUninformativeIdentity(value: string | undefined): boolean;
+export declare function firmwareIdentityLabel(revision: string | undefined): string | undefined;
+export declare function modemHardwareLabel(identity: ModemHardwareIdentity): string;
+export declare function modemHardwareName(identity: ModemHardwareIdentity): string;

package/dist/domain/modem-presentation.js

@@ -0,0 +1,39 @@
+const BARE_NUMERAL_RE = /^\d{1,4}$/;
+const MMCLI_EMPTY = '--';
+export function isUninformativeIdentity(value) {
+    const trimmed = value?.trim();
+    return (trimmed === undefined ||
+        trimmed === '' ||
+        trimmed === MMCLI_EMPTY ||
+        BARE_NUMERAL_RE.test(trimmed));
+}
+export function firmwareIdentityLabel(revision) {
+    const trimmed = revision?.trim();
+    if (!trimmed || trimmed === MMCLI_EMPTY)
+        return undefined;
+    const head = trimmed
+        .replace(/\s*\[[^\]]*]\s*$/, '')
+        .trim()
+        .split(/\s{2,}/)[0]
+        ?.trim() ?? '';
+    return head.length >= 3 && /[A-Za-z]/.test(head) ? head : undefined;
+}
+export function modemHardwareLabel(identity) {
+    const model = identity.model?.trim();
+    if (model !== undefined && !isUninformativeIdentity(model))
+        return model;
+    const firmware = firmwareIdentityLabel(identity.firmwareRevision);
+    if (firmware !== undefined)
+        return firmware;
+    const manufacturer = identity.manufacturer?.trim();
+    return manufacturer !== undefined && !isUninformativeIdentity(manufacturer)
+        ? manufacturer
+        : 'Cellular modem';
+}
+export function modemHardwareName(identity) {
+    const label = modemHardwareLabel(identity);
+    const equipmentId = identity.equipmentId?.trim();
+    return !equipmentId || equipmentId === MMCLI_EMPTY
+        ? label
+        : `${label} - ${equipmentId.slice(-5)}`;
+}

package/dist/domain/observation.d.ts

@@ -0,0 +1,39 @@
+import type { Brand } from './brand.js';
+import type { DeviceGeneration } from './generation.js';
+import type { StableKey } from './physical-identity.js';
+import type { EpochMillis } from './state.js';
+export type SourceEpoch = Brand<number, 'SourceEpoch'>;
+export declare function sourceEpoch(value: number): SourceEpoch;
+export type ObservationAuthority = 'authoritative' | 'derived' | 'advisory';
+export type ObservationFreshness = {
+    readonly state: 'fresh';
+} | {
+    readonly state: 'stale';
+    readonly since: EpochMillis;
+    readonly reason: 'source-epoch-superseded' | 'ttl-expired' | 'source-degraded';
+} | {
+    readonly state: 'unavailable';
+    readonly since: EpochMillis;
+    readonly reason: 'source-unavailable' | 'device-absent' | 'provider-unavailable';
+};
+type ObservationBase = {
+    readonly stableKey: StableKey;
+    readonly generation: DeviceGeneration;
+    readonly source: string;
+    readonly sourceEpoch: SourceEpoch;
+    readonly observedAt: EpochMillis;
+    readonly authority: ObservationAuthority;
+};
+/** A value is retained while stale, but unavailable is explicit and carries no invented value. */
+export type ObservationEnvelope<T> = (ObservationBase & {
+    readonly freshness: Extract<ObservationFreshness, {
+        readonly state: 'fresh' | 'stale';
+    }>;
+    readonly value: T;
+}) | (ObservationBase & {
+    readonly freshness: Extract<ObservationFreshness, {
+        readonly state: 'unavailable';
+    }>;
+    readonly value: null;
+});
+export {};

package/dist/domain/observation.js

@@ -0,0 +1,4 @@
+import { nonNegativeInteger } from './brand.js';
+export function sourceEpoch(value) {
+    return nonNegativeInteger(value, 'sourceEpoch');
+}