@ceralive/modem-control 0.1.0

package/src/domain/policy.ts

@@ -0,0 +1,137 @@
+// Durable desired-state policy — the operator's intent for one modem.
+//
+// A2.1 stubbed this shape so the domain could enforce "an ambiguous identity may
+// never bind durable policy" (see `policyBindingKey`). A2.2 owns the REAL
+// definition below: the full connection / roaming / radio / simSlot / recovery /
+// usage intent the desired-state planner reconciles (see `../ports/reconcile`).
+
+import type { EquipmentId, LogicalSlotId, ModemIdentity } from './identity';
+import { assertCanBindPolicy } from './identity';
+import type { RadioAccessTechnology } from './state';
+
+/**
+ * The subset of identity a durable policy is allowed to key off.
+ *
+ * Deliberately excludes `runtimePath` (never persisted) and `subscriptionId`
+ * (sensitive). Durable policy binds to the physical slot when known, always
+ * anchored by the equipment id — never to a per-boot handle or a subscriber id.
+ */
+export interface PolicyBindingKey {
+	readonly logicalSlotId?: LogicalSlotId;
+	readonly equipmentId: EquipmentId;
+}
+
+/** IP address family a connection requests. */
+export type IpFamily = 'ipv4' | 'ipv6' | 'ipv4v6';
+
+/**
+ * Connection credentials. TODAY'S SEMANTICS (draft §round-5 auth): these are
+ * persisted ONLY in the NetworkManager profile; the controller keeps them
+ * transient in memory and NEVER writes them to its own store. `password` is
+ * SENSITIVE and is ALWAYS redacted in logs / output / receipts (see `../redact`).
+ */
+export interface DesiredAuth {
+	readonly username?: string;
+	/** SENSITIVE — always redacted; NM-profile-persisted only, transient in memory. */
+	readonly password?: string;
+}
+
+/** The data-connection intent. `apn: "auto"` selects NM Auto-APN (A4.1). */
+export interface DesiredConnection {
+	readonly apn: 'auto' | string;
+	readonly ipFamily: IpFamily;
+	readonly auth?: DesiredAuth;
+	/**
+	 * Manual operator selection (`gsm.network-id`) — pin registration to a specific
+	 * PLMN. Honored only while roaming (A4.1 amendment): the NM profile writes
+	 * `gsm.network-id = roaming ? networkId : ""`, so it is cleared when roaming is off.
+	 */
+	readonly networkId?: string;
+}
+
+/**
+ * Radio access-technology intent. `preferenceOrdered` is ranked most-preferred
+ * first ("prefer 5G" ⇒ `['5gnr', 'lte', …]`); it must be honored as a PREFERENCE,
+ * never silently narrowed to an exclusive set — the planner reports `unsupported`
+ * when the top preference is unavailable (never a silent downgrade). `allowedSet`,
+ * when present, hard-limits the technologies the modem may use at all.
+ */
+export interface DesiredRadio {
+	readonly preferenceOrdered: readonly RadioAccessTechnology[];
+	readonly allowedSet?: ReadonlySet<RadioAccessTechnology>;
+}
+
+/**
+ * Recovery intent. DISABLED BY DEFAULT — the evidence-gated recovery ladder (A3.4)
+ * adds the per-step budgets / cooldowns; in Phase A `enabled` defaults to `false`
+ * and no recovery action is ever taken unless it is explicitly turned on.
+ */
+export interface DesiredRecovery {
+	readonly enabled: boolean;
+}
+
+/** Data-usage policy — local-controller owned (see ports README ownership table). */
+export interface DesiredUsage {
+	/** Day of month (1–31) the usage cycle resets; UTC, month-length clamped (A4.3). */
+	readonly cycleDay?: number;
+	/** Advisory threshold in bytes; crossing it raises an advisory, never gates. */
+	readonly thresholdBytes?: number;
+}
+
+/**
+ * Operator-authored durable cellular policy, bound to a high/medium-confidence
+ * identity via `boundTo` (a low-confidence identity cannot produce a binding key,
+ * so it can never be named here).
+ *
+ *   - enabled    — desired NM activation state (`enabled ≙ NM-activation`).
+ *   - connection — APN (or `"auto"`), IP family, optional (redacted) credentials.
+ *   - roaming    — allow the modem to register while roaming.
+ *   - radio      — ranked RAT preference (+ optional hard-allowed set).
+ *   - simSlot    — preferred primary SIM slot (1-based; multi-slot modems).
+ *   - recovery   — recovery-ladder intent (disabled by default).
+ *   - usage      — data-usage cycle + advisory threshold.
+ */
+export interface DesiredCellularPolicy {
+	readonly boundTo: PolicyBindingKey;
+	readonly enabled: boolean;
+	readonly connection: DesiredConnection;
+	readonly roaming: boolean;
+	readonly radio: DesiredRadio;
+	readonly simSlot?: number;
+	readonly recovery: DesiredRecovery;
+	readonly usage: DesiredUsage;
+}
+
+/** Recovery disabled — the Phase-A default (A3.4 adds budgets / cooldowns). */
+export const RECOVERY_DISABLED: DesiredRecovery = { enabled: false };
+
+/**
+ * Build a sensible default policy for a bindable identity: NM activation on,
+ * Auto-APN, dual-stack IP, roaming off, prefer newest RAT down to GSM, recovery
+ * disabled, no usage limits. Concrete adapters and the planner refine from here.
+ */
+export function defaultCellularPolicy(boundTo: PolicyBindingKey): DesiredCellularPolicy {
+	return {
+		boundTo,
+		enabled: true,
+		connection: { apn: 'auto', ipFamily: 'ipv4v6' },
+		roaming: false,
+		radio: { preferenceOrdered: ['5gnr', 'lte', 'umts', 'gsm'] },
+		recovery: RECOVERY_DISABLED,
+		usage: {},
+	};
+}
+
+/**
+ * Derive the durable binding key for an identity, REFUSING low-confidence
+ * (ambiguous) identities. This is the structural gate that makes it impossible to
+ * bind durable policy to a duplicate/zero-IMEI modem: no key can be produced, so
+ * no `DesiredCellularPolicy` can name it. Throws `PolicyBindingRefusedError`.
+ */
+export function policyBindingKey(identity: ModemIdentity): PolicyBindingKey {
+	assertCanBindPolicy(identity);
+	// exactOptionalPropertyTypes: only include logicalSlotId when actually present.
+	return identity.logicalSlotId !== undefined
+		? { logicalSlotId: identity.logicalSlotId, equipmentId: identity.equipmentId }
+		: { equipmentId: identity.equipmentId };
+}

package/src/domain/snapshot.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, test } from 'bun:test';
+import { ImpossibleStateError, RevisionMonotonicityError } from './errors';
+import { imeiEquipmentId, type ModemIdentity, runtimePath } from './identity';
+import {
+	applyTransition,
+	type CellularSnapshot,
+	createSnapshot,
+	initialSnapshot,
+	markSourceUnavailable,
+	revision,
+	supersede,
+} from './snapshot';
+import {
+	type DataInterface,
+	epochMillis,
+	isRegistered,
+	MM_STATES_REQUIRING_RADIO,
+	type MmState,
+	type NmActivation,
+	type RadioAccessTechnology,
+	type RadioPower,
+	type RecoveryStage,
+	type RecoveryState,
+	type RegistrationStatus,
+	SIM_LOCK_REQUIRES_CARD,
+	type SimLock,
+	type SimSlot,
+} from './state';
+
+const IDENTITY: ModemIdentity = {
+	equipmentId: imeiEquipmentId('490154203237518'),
+	runtimePath: runtimePath('/org/freedesktop/ModemManager1/Modem/0'),
+};
+
+describe('reducers', () => {
+	test('initialSnapshot is a valid absent baseline at revision 0', () => {
+		const snapshot = initialSnapshot(IDENTITY);
+		expect(snapshot.presence).toBe('absent');
+		expect(snapshot.revision).toBe(revision(0));
+		expect(() => createSnapshot(snapshot)).not.toThrow();
+	});
+
+	test('applyTransition bumps the revision by exactly one', () => {
+		const start = initialSnapshot(IDENTITY);
+		const next = applyTransition(start, { reconcileStatus: 'reconciling' });
+		expect(next.revision).toBe(revision(1));
+		expect(next.reconcileStatus).toBe('reconciling');
+	});
+
+	test('applyTransition re-validates and throws on an impossible patch', () => {
+		const start = applyTransition(initialSnapshot(IDENTITY), {
+			presence: 'present',
+			radioPower: 'on',
+			mmState: 'registered',
+			registration: { status: 'home', activeRats: new Set(['lte']) },
+		});
+		expect(() => applyTransition(start, { presence: 'absent' })).toThrow(ImpossibleStateError);
+	});
+
+	test('markSourceUnavailable keeps presence and marks the source, bumping revision', () => {
+		const present = applyTransition(initialSnapshot(IDENTITY), { presence: 'present' });
+		const unavailable = markSourceUnavailable(present);
+		expect(unavailable.presence).toBe('present');
+		expect(unavailable.sourceHealth).toBe('sourceUnavailable');
+		expect(unavailable.revision).toBe(revision(2));
+	});
+
+	test('supersede rejects a stale or equal revision', () => {
+		const current = applyTransition(initialSnapshot(IDENTITY), { reconcileStatus: 'converged' });
+		const stale: CellularSnapshot = { ...initialSnapshot(IDENTITY), revision: revision(0) };
+		expect(() => supersede(current, stale)).toThrow(RevisionMonotonicityError);
+	});
+
+	test('supersede accepts a strictly-newer valid snapshot', () => {
+		const current = initialSnapshot(IDENTITY);
+		const newer: CellularSnapshot = { ...initialSnapshot(IDENTITY), revision: revision(9) };
+		expect(supersede(current, newer).revision).toBe(revision(9));
+	});
+});
+
+// --- randomized property test ----------------------------------------------
+
+const MM_STATES: readonly MmState[] = [
+	'failed',
+	'unknown',
+	'initializing',
+	'locked',
+	'disabled',
+	'enabled',
+	'searching',
+	'registered',
+	'connecting',
+	'connected',
+];
+const REG_STATUSES: readonly RegistrationStatus[] = [
+	'idle',
+	'home',
+	'searching',
+	'denied',
+	'unknown',
+	'roaming',
+];
+const NM_STATES: readonly NmActivation[] = [
+	'unmanaged',
+	'unavailable',
+	'disconnected',
+	'activating',
+	'activated',
+	'failed',
+];
+const POWERS: readonly RadioPower[] = ['unknown', 'off', 'low', 'on'];
+const STAGES: readonly RecoveryStage[] = [
+	'idle',
+	'attributing',
+	'nm-cycle',
+	'mm-cycle',
+	'reset',
+	'power-cycle',
+	'cooldown',
+	'exhausted',
+];
+const LOCKS: readonly SimLock[] = [
+	'unknown',
+	'none',
+	'sim-pin',
+	'sim-puk',
+	'net-pers',
+	'permanently-blocked',
+];
+const RATS: readonly RadioAccessTechnology[] = ['gsm', 'umts', 'lte', '5gnr'];
+
+/** Deterministic xorshift32 PRNG so a failing case is always reproducible. */
+function makePrng(seed: number): () => number {
+	let state = seed >>> 0 || 1;
+	return () => {
+		state ^= state << 13;
+		state >>>= 0;
+		state ^= state >> 17;
+		state ^= state << 5;
+		state >>>= 0;
+		return state / 0xffffffff;
+	};
+}
+
+function pick<T>(rng: () => number, values: readonly T[]): T {
+	const index = Math.min(values.length - 1, Math.floor(rng() * values.length));
+	return values[index] as T;
+}
+
+function randomSnapshot(rng: () => number): CellularSnapshot {
+	const rats = new Set<RadioAccessTechnology>();
+	for (const rat of RATS) {
+		if (rng() < 0.5) {
+			rats.add(rat);
+		}
+	}
+
+	const slotCount = Math.floor(rng() * 3);
+	const simSlots: SimSlot[] = [];
+	for (let i = 0; i < slotCount; i += 1) {
+		simSlots.push({
+			index: i + 1,
+			occupied: rng() < 0.7,
+			active: rng() < 0.5,
+			lock: pick(rng, LOCKS),
+		});
+	}
+
+	let dataInterface: DataInterface;
+	if (rng() < 0.6) {
+		dataInterface = rng() < 0.5 ? { present: true, name: 'wwan0' } : { present: true };
+	} else {
+		dataInterface = rng() < 0.5 ? { present: false } : { present: false, name: 'wwan0' };
+	}
+
+	const stage = pick(rng, STAGES);
+	const attempts = Math.floor(rng() * 4);
+	const recoveryState: RecoveryState =
+		rng() < 0.5
+			? { stage, attempts, cooldownUntil: epochMillis(1_700_000_000_000) }
+			: { stage, attempts };
+
+	return {
+		identity: IDENTITY,
+		presence: rng() < 0.5 ? 'present' : 'absent',
+		sourceHealth: pick(rng, ['live', 'stale', 'sourceUnavailable'] as const),
+		simSlots,
+		radioPower: pick(rng, POWERS),
+		mmState: pick(rng, MM_STATES),
+		registration: { status: pick(rng, REG_STATUSES), activeRats: rats },
+		nmActivation: pick(rng, NM_STATES),
+		dataInterface,
+		reconcileStatus: pick(rng, [
+			'converged',
+			'reconciling',
+			'pending',
+			'divergent',
+			'unsupported',
+		] as const),
+		recoveryState,
+		revision: revision(Math.floor(rng() * 1_000_000)),
+	};
+}
+
+/** Independent restatement of the invariants — never calls the guards under test. */
+function assertInvariants(s: CellularSnapshot): void {
+	if (isRegistered(s.registration.status)) {
+		expect(s.presence).toBe('present');
+		expect(s.radioPower).not.toBe('off');
+		expect(s.registration.activeRats.size).toBeGreaterThan(0);
+	}
+	if (MM_STATES_REQUIRING_RADIO.has(s.mmState)) {
+		expect(s.presence).toBe('present');
+	}
+	if (s.nmActivation === 'activated') {
+		expect(s.presence).toBe('present');
+		expect(s.dataInterface.present).toBe(true);
+		expect(s.mmState).toBe('connected');
+	}
+	if (s.radioPower === 'off') {
+		const onAir =
+			MM_STATES_REQUIRING_RADIO.has(s.mmState) ||
+			s.registration.status === 'searching' ||
+			s.nmActivation === 'activating' ||
+			s.nmActivation === 'activated';
+		expect(onAir).toBe(false);
+	}
+	expect(s.simSlots.filter((slot) => slot.active).length).toBeLessThanOrEqual(1);
+	for (const slot of s.simSlots) {
+		if (!slot.occupied) {
+			expect(SIM_LOCK_REQUIRES_CARD.has(slot.lock)).toBe(false);
+		}
+	}
+	if (!s.dataInterface.present) {
+		expect(s.dataInterface.name).toBeUndefined();
+	}
+	expect(s.recoveryState.attempts).toBeGreaterThanOrEqual(0);
+	expect(s.recoveryState.cooldownUntil !== undefined).toBe(s.recoveryState.stage === 'cooldown');
+}
+
+describe('randomized property test', () => {
+	test('every constructed snapshot upholds the invariants; every rejection is typed', () => {
+		const rng = makePrng(0x9e3779b9);
+		let constructed = 0;
+		let rejected = 0;
+
+		for (let i = 0; i < 5000; i += 1) {
+			const candidate = randomSnapshot(rng);
+			let built: CellularSnapshot | null = null;
+			try {
+				built = createSnapshot(candidate);
+			} catch (error) {
+				rejected += 1;
+				expect(error).toBeInstanceOf(ImpossibleStateError);
+				continue;
+			}
+			constructed += 1;
+			assertInvariants(built);
+			// The plan's headline invariant, stated on its own.
+			expect(isRegistered(built.registration.status) && built.presence === 'absent').toBe(false);
+		}
+
+		expect(constructed).toBeGreaterThan(0);
+		expect(rejected).toBeGreaterThan(0);
+	});
+});

package/src/domain/snapshot.ts

@@ -0,0 +1,120 @@
+// CellularSnapshot — the whole coherent state of one modem at one revision.
+//
+// A snapshot composes the identity and all eight orthogonal dimensions plus a
+// monotonic `revision`. Every snapshot that exists has passed the guards: the
+// constructors here are the ONLY sanctioned way to build or advance one, so an
+// impossible combination can never be observed downstream. Revisions strictly
+// increase, letting the observer (A3.1) and consumers order and dedupe events.
+
+import type { Brand } from './brand';
+import { nonNegativeInteger } from './brand';
+import { RevisionMonotonicityError } from './errors';
+import { assertSnapshot } from './guards';
+import type { ModemIdentity } from './identity';
+import type {
+	DataInterface,
+	MmState,
+	NmActivation,
+	Presence,
+	RadioPower,
+	ReconcileStatus,
+	RecoveryState,
+	Registration,
+	SimSlot,
+	SourceHealth,
+} from './state';
+
+/** A monotonically increasing snapshot revision. */
+export type Revision = Brand<number, 'Revision'>;
+
+/** Construct a `Revision` from a non-negative integer. */
+export function revision(value: number): Revision {
+	return nonNegativeInteger(value, 'revision') as Revision;
+}
+
+/** The revision every fresh identity starts at. */
+export const INITIAL_REVISION: Revision = revision(0);
+
+/** The next revision after `current`. */
+export function nextRevision(current: Revision): Revision {
+	return (current + 1) as Revision;
+}
+
+/** The full coherent state of one modem at one point in time. */
+export interface CellularSnapshot {
+	readonly identity: ModemIdentity;
+	readonly presence: Presence;
+	readonly sourceHealth: SourceHealth;
+	readonly simSlots: readonly SimSlot[];
+	readonly radioPower: RadioPower;
+	readonly mmState: MmState;
+	readonly registration: Registration;
+	readonly nmActivation: NmActivation;
+	readonly dataInterface: DataInterface;
+	readonly reconcileStatus: ReconcileStatus;
+	readonly recoveryState: RecoveryState;
+	readonly revision: Revision;
+}
+
+/** A partial update to a snapshot's dimensions; `revision` is managed, not patched. */
+export type SnapshotPatch = Partial<Omit<CellularSnapshot, 'revision'>>;
+
+/**
+ * Validate and return a snapshot. The guards run here: an impossible combination
+ * throws `ImpossibleStateError` rather than producing an incoherent value. This
+ * is the sole sanctioned constructor for an arbitrary snapshot.
+ */
+export function createSnapshot(fields: CellularSnapshot): CellularSnapshot {
+	assertSnapshot(fields);
+	return fields;
+}
+
+/** A valid baseline for a freshly-observed-but-absent modem, at revision 0. */
+export function initialSnapshot(identity: ModemIdentity): CellularSnapshot {
+	return {
+		identity,
+		presence: 'absent',
+		sourceHealth: 'live',
+		simSlots: [],
+		radioPower: 'unknown',
+		mmState: 'unknown',
+		registration: { status: 'unknown', activeRats: new Set() },
+		nmActivation: 'unavailable',
+		dataInterface: { present: false },
+		reconcileStatus: 'pending',
+		recoveryState: { stage: 'idle', attempts: 0 },
+		revision: INITIAL_REVISION,
+	};
+}
+
+/**
+ * Apply a dimension patch, bump the revision, and re-validate. Monotonicity is
+ * automatic (revision always advances by one); an impossible result throws.
+ */
+export function applyTransition(prev: CellularSnapshot, patch: SnapshotPatch): CellularSnapshot {
+	const next: CellularSnapshot = { ...prev, ...patch, revision: nextRevision(prev.revision) };
+	assertSnapshot(next);
+	return next;
+}
+
+/**
+ * Replace a snapshot with a fully-formed successor that carries its own revision
+ * (the observer path). Enforces strict monotonicity — a stale or equal revision
+ * throws `RevisionMonotonicityError` — and validates the successor.
+ */
+export function supersede(prev: CellularSnapshot, next: CellularSnapshot): CellularSnapshot {
+	if (next.revision <= prev.revision) {
+		throw new RevisionMonotonicityError(prev.revision, next.revision);
+	}
+	assertSnapshot(next);
+	return next;
+}
+
+/**
+ * The source (MM daemon / bus) dropped: mark the data `sourceUnavailable` while
+ * KEEPING presence and all other facts. Stale is never removal — only an
+ * authoritative snapshot confirms absence (draft §Oracle round-1 lifecycle).
+ */
+export function markSourceUnavailable(prev: CellularSnapshot): CellularSnapshot {
+	return applyTransition(prev, { sourceHealth: 'sourceUnavailable' });
+}