@ceralive/modem-control 1.0.0 → 1.1.0

package/src/domain/guards.test.ts

@@ -1,218 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { type ImpossibleStateCode, ImpossibleStateError } from './errors';
-import { imeiEquipmentId, type ModemIdentity, runtimePath } from './identity';
-import type { CellularSnapshot } from './snapshot';
-import { createSnapshot, revision } from './snapshot';
-import { epochMillis } from './state';
-
-const IDENTITY: ModemIdentity = {
-	equipmentId: imeiEquipmentId('490154203237518'),
-	runtimePath: runtimePath('/org/freedesktop/ModemManager1/Modem/0'),
-};
-
-/** A fully valid registered + connected + NM-activated snapshot to mutate from. */
-function connectedBase(): CellularSnapshot {
-	return {
-		identity: IDENTITY,
-		presence: 'present',
-		sourceHealth: 'live',
-		simSlots: [{ index: 1, occupied: true, active: true, lock: 'none' }],
-		radioPower: 'on',
-		mmState: 'connected',
-		registration: { status: 'home', activeRats: new Set(['lte']) },
-		nmActivation: 'activated',
-		dataInterface: { present: true, name: 'wwan0' },
-		reconcileStatus: 'converged',
-		recoveryState: { stage: 'idle', attempts: 0 },
-		revision: revision(5),
-	};
-}
-
-function expectImpossible(fields: CellularSnapshot, code: ImpossibleStateCode): void {
-	expect(() => createSnapshot(fields)).toThrow(ImpossibleStateError);
-	try {
-		createSnapshot(fields);
-	} catch (error) {
-		expect(error).toBeInstanceOf(ImpossibleStateError);
-		expect((error as ImpossibleStateError).code).toBe(code);
-		return;
-	}
-	throw new Error(`expected ${code} to throw`);
-}
-
-describe('valid snapshots pass', () => {
-	test('a coherent connected snapshot constructs', () => {
-		expect(() => createSnapshot(connectedBase())).not.toThrow();
-	});
-
-	test('mmState locked WITH an occupied pin-locked slot is valid', () => {
-		const s: CellularSnapshot = {
-			...connectedBase(),
-			mmState: 'locked',
-			nmActivation: 'disconnected',
-			registration: { status: 'idle', activeRats: new Set() },
-			radioPower: 'on',
-			dataInterface: { present: false },
-			simSlots: [{ index: 1, occupied: true, active: true, lock: 'sim-pin' }],
-		};
-		expect(() => createSnapshot(s)).not.toThrow();
-	});
-
-	test('a cooldown recovery state with a deadline is valid', () => {
-		const s: CellularSnapshot = {
-			...connectedBase(),
-			recoveryState: {
-				stage: 'cooldown',
-				attempts: 2,
-				cooldownUntil: epochMillis(1_700_000_000_000),
-			},
-		};
-		expect(() => createSnapshot(s)).not.toThrow();
-	});
-});
-
-describe('impossible combinations throw typed errors', () => {
-	test('registered while absent (the named guard)', () => {
-		expectImpossible({ ...connectedBase(), presence: 'absent' }, 'registered-while-absent');
-	});
-
-	test('registered with the radio off', () => {
-		expectImpossible({ ...connectedBase(), radioPower: 'off' }, 'registered-radio-off');
-	});
-
-	test('registered with an empty RAT set', () => {
-		expectImpossible(
-			{ ...connectedBase(), registration: { status: 'home', activeRats: new Set() } },
-			'registered-empty-rat-set',
-		);
-	});
-
-	test('an active MM state while absent', () => {
-		expectImpossible(
-			{
-				...connectedBase(),
-				presence: 'absent',
-				mmState: 'enabled',
-				registration: { status: 'idle', activeRats: new Set() },
-				nmActivation: 'disconnected',
-				dataInterface: { present: false },
-			},
-			'active-state-while-absent',
-		);
-	});
-
-	test('the radio off while searching', () => {
-		expectImpossible(
-			{
-				...connectedBase(),
-				radioPower: 'off',
-				mmState: 'searching',
-				registration: { status: 'searching', activeRats: new Set() },
-				nmActivation: 'disconnected',
-				dataInterface: { present: false },
-			},
-			'radio-off-while-active',
-		);
-	});
-
-	test('NM activated while absent', () => {
-		expectImpossible(
-			{
-				...connectedBase(),
-				presence: 'absent',
-				mmState: 'disabled',
-				registration: { status: 'idle', activeRats: new Set() },
-				dataInterface: { present: false },
-			},
-			'nm-activated-while-absent',
-		);
-	});
-
-	test('NM activated without a data interface', () => {
-		expectImpossible(
-			{ ...connectedBase(), dataInterface: { present: false } },
-			'nm-activated-without-interface',
-		);
-	});
-
-	test('NM activated while MM is not connected', () => {
-		expectImpossible(
-			{ ...connectedBase(), mmState: 'registered' },
-			'nm-activated-without-mm-connected',
-		);
-	});
-
-	test('more than one active SIM slot', () => {
-		expectImpossible(
-			{
-				...connectedBase(),
-				simSlots: [
-					{ index: 1, occupied: true, active: true, lock: 'none' },
-					{ index: 2, occupied: true, active: true, lock: 'none' },
-				],
-			},
-			'multiple-active-sim-slots',
-		);
-	});
-
-	test('a locked SIM in an empty slot', () => {
-		expectImpossible(
-			{
-				...connectedBase(),
-				simSlots: [{ index: 1, occupied: false, active: false, lock: 'sim-pin' }],
-			},
-			'locked-sim-in-empty-slot',
-		);
-	});
-
-	test('MM locked without any locked SIM', () => {
-		expectImpossible(
-			{
-				...connectedBase(),
-				mmState: 'locked',
-				nmActivation: 'disconnected',
-				registration: { status: 'idle', activeRats: new Set() },
-				dataInterface: { present: false },
-				simSlots: [{ index: 1, occupied: true, active: true, lock: 'none' }],
-			},
-			'mm-locked-without-sim-lock',
-		);
-	});
-
-	test('a data-interface name without presence', () => {
-		expectImpossible(
-			{
-				...connectedBase(),
-				mmState: 'disabled',
-				nmActivation: 'disconnected',
-				registration: { status: 'idle', activeRats: new Set() },
-				dataInterface: { present: false, name: 'wwan0' },
-			},
-			'data-interface-name-without-presence',
-		);
-	});
-
-	test('a negative recovery attempt count', () => {
-		expectImpossible(
-			{ ...connectedBase(), recoveryState: { stage: 'nm-cycle', attempts: -1 } },
-			'recovery-attempts-negative',
-		);
-	});
-
-	test('a cooldown deadline outside the cooldown stage', () => {
-		expectImpossible(
-			{
-				...connectedBase(),
-				recoveryState: { stage: 'nm-cycle', attempts: 1, cooldownUntil: epochMillis(123) },
-			},
-			'recovery-cooldown-stage-mismatch',
-		);
-	});
-
-	test('idle recovery carrying attempts', () => {
-		expectImpossible(
-			{ ...connectedBase(), recoveryState: { stage: 'idle', attempts: 3 } },
-			'recovery-idle-with-attempts',
-		);
-	});
-});

package/src/domain/guards.ts

@@ -1,144 +0,0 @@
-// 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 type { ImpossibleStateCode } from './errors';
-import { ImpossibleStateError } from './errors';
-import type { CellularSnapshot } from './snapshot';
-import { isRegistered, MM_STATES_REQUIRING_RADIO, SIM_LOCK_REQUIRES_CARD } from './state';
-
-type Violation = { readonly code: ImpossibleStateCode; readonly detail: string } | null;
-
-function checkRegistration(s: CellularSnapshot): Violation {
-	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: CellularSnapshot): boolean {
-	return (
-		MM_STATES_REQUIRING_RADIO.has(s.mmState) ||
-		s.registration.status === 'searching' ||
-		s.nmActivation === 'activating' ||
-		s.nmActivation === 'activated'
-	);
-}
-
-function checkRadioAndPresence(s: CellularSnapshot): Violation {
-	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: CellularSnapshot): Violation {
-	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: CellularSnapshot): Violation {
-	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: CellularSnapshot): Violation {
-	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: CellularSnapshot): Violation {
-	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: ReadonlyArray<(s: CellularSnapshot) => Violation> = [
-	checkRegistration,
-	checkRadioAndPresence,
-	checkNmActivation,
-	checkSimSlots,
-	checkDataInterface,
-	checkRecovery,
-];
-
-/** Return the first impossible-combination code the snapshot violates, or null. */
-export function checkSnapshot(snapshot: CellularSnapshot): ImpossibleStateCode | null {
-	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: CellularSnapshot): void {
-	for (const check of CHECKS) {
-		const violation = check(snapshot);
-		if (violation !== null) {
-			throw new ImpossibleStateError(violation.code, violation.detail);
-		}
-	}
-}

package/src/domain/identity.test.ts

@@ -1,83 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { PolicyBindingRefusedError } from './errors';
-import {
-	canBindPolicy,
-	demoteToLowConfidence,
-	imeiEquipmentId,
-	type ModemIdentity,
-	NO_EQUIPMENT_ID,
-	runtimePath,
-	serialEquipmentId,
-} from './identity';
-import { policyBindingKey } from './policy';
-
-const PATH = runtimePath('/org/freedesktop/ModemManager1/Modem/0');
-
-function identityWith(equipmentId: ModemIdentity['equipmentId']): ModemIdentity {
-	return { equipmentId, runtimePath: PATH };
-}
-
-describe('equipment id confidence grading', () => {
-	test('a canonical 15-digit IMEI grades high', () => {
-		const id = imeiEquipmentId('490154203237518');
-		expect(id).toEqual({ provenance: 'imei', value: '490154203237518', confidence: 'high' });
-	});
-
-	test('an all-zeros IMEI grades low (ambiguous placeholder)', () => {
-		expect(imeiEquipmentId('000000000000000').confidence).toBe('low');
-	});
-
-	test('a blank IMEI grades low', () => {
-		expect(imeiEquipmentId('   ').confidence).toBe('low');
-	});
-
-	test('a non-standard IMEI shape grades medium', () => {
-		expect(imeiEquipmentId('49015420').confidence).toBe('medium');
-	});
-
-	test('a serial fallback caps at medium', () => {
-		expect(serialEquipmentId('SN-ABC-123').confidence).toBe('medium');
-	});
-
-	test('the none provenance carries no value and is always low', () => {
-		expect(NO_EQUIPMENT_ID).toEqual({ provenance: 'none', confidence: 'low' });
-	});
-});
-
-describe('duplicate demotion', () => {
-	test('a duplicate IMEI is demoted to low confidence but keeps its value', () => {
-		const original = imeiEquipmentId('490154203237518');
-		const demoted = demoteToLowConfidence(original);
-		expect(demoted).toEqual({ provenance: 'imei', value: '490154203237518', confidence: 'low' });
-	});
-
-	test('demoting a none id is a no-op', () => {
-		expect(demoteToLowConfidence(NO_EQUIPMENT_ID)).toBe(NO_EQUIPMENT_ID);
-	});
-});
-
-describe('durable policy binding gate', () => {
-	test('a high-confidence identity may bind policy and yields a key', () => {
-		const identity = identityWith(imeiEquipmentId('490154203237518'));
-		expect(canBindPolicy(identity)).toBe(true);
-		expect(policyBindingKey(identity)).toEqual({ equipmentId: identity.equipmentId });
-	});
-
-	test('a low-confidence (zero IMEI) identity is refused', () => {
-		const identity = identityWith(imeiEquipmentId('000000000000000'));
-		expect(canBindPolicy(identity)).toBe(false);
-		expect(() => policyBindingKey(identity)).toThrow(PolicyBindingRefusedError);
-	});
-
-	test('a duplicate-demoted identity is refused', () => {
-		const identity = identityWith(demoteToLowConfidence(imeiEquipmentId('490154203237518')));
-		expect(canBindPolicy(identity)).toBe(false);
-		expect(() => policyBindingKey(identity)).toThrow(PolicyBindingRefusedError);
-	});
-
-	test('a none-provenance identity is refused (never binds durable policy)', () => {
-		const identity = identityWith(NO_EQUIPMENT_ID);
-		expect(canBindPolicy(identity)).toBe(false);
-		expect(() => policyBindingKey(identity)).toThrow(PolicyBindingRefusedError);
-	});
-});

package/src/domain/identity.ts

@@ -1,165 +0,0 @@
-// 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 type { Brand } from './brand';
-import { nonEmptyString } from './brand';
-import { PolicyBindingRefusedError } from './errors';
-
-/**
- * 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 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;
-	/** NEVER PERSISTED — per-boot runtime handle only. */
-	readonly runtimePath: RuntimePath;
-}
-
-// --- constructors ----------------------------------------------------------
-
-/** Construct a `LogicalSlotId` from a non-empty string. */
-export function logicalSlotId(value: string): LogicalSlotId {
-	return nonEmptyString(value, 'logicalSlotId') as LogicalSlotId;
-}
-
-/** Construct a `SubscriptionId` from a non-empty string. */
-export function subscriptionId(value: string): SubscriptionId {
-	return nonEmptyString(value, 'subscriptionId') as SubscriptionId;
-}
-
-/** Construct a `RuntimePath` from a non-empty string. */
-export function runtimePath(value: string): RuntimePath {
-	return nonEmptyString(value, 'runtimePath') as 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: string): IdentityConfidence {
-	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: EquipmentId = { provenance: 'none', confidence: 'low' };
-
-/** Build an IMEI-provenance equipment id, grading confidence from the value. */
-export function imeiEquipmentId(value: string): EquipmentId {
-	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: string): EquipmentId {
-	const confidence: IdentityConfidence = 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: EquipmentId): EquipmentId {
-	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: ModemIdentity): boolean {
-	return identity.equipmentId.confidence !== 'low';
-}
-
-/** Throw `PolicyBindingRefusedError` if the identity may not bind durable policy. */
-export function assertCanBindPolicy(identity: ModemIdentity): void {
-	if (!canBindPolicy(identity)) {
-		throw new PolicyBindingRefusedError(
-			`equipment id (provenance=${identity.equipmentId.provenance}) is low-confidence`,
-		);
-	}
-}

package/src/domain/index.ts

@@ -1,12 +0,0 @@
-// 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';
-export * from './errors';
-export * from './guards';
-export * from './identity';
-export * from './policy';
-export * from './snapshot';
-export * from './state';