@ceralive/modem-control 1.0.0 → 1.2.0

package/src/domain/snapshot.test.ts

@@ -1,266 +0,0 @@
-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

@@ -1,120 +0,0 @@
-// 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' });
-}

package/src/index.test.ts

@@ -1,6 +0,0 @@
-import { expect, test } from 'bun:test';
-import { PACKAGE_NAME } from './index';
-
-test('control package exposes its name', () => {
-	expect(PACKAGE_NAME).toBe('@ceralive/modem-control');
-});

package/src/index.ts

@@ -1,15 +0,0 @@
-// @ceralive/modem-control — package entry point.
-//
-// Phase A: the domain model (identity + orthogonal state + revisions) under
-// `./domain`, the MM / NM / Router port contracts + desired-state planner under
-// `./ports`, the redaction module (`./redact`), and the epoch-scoped ModemManager
-// D-Bus observer under `./backend`. The NetworkManager adapter, USB composition-mode
-// model, and data-usage sampler land in later waves.
-
-export const PACKAGE_NAME = '@ceralive/modem-control';
-
-export * from './backend';
-export * from './domain';
-export * from './ports';
-export * from './redact';
-export * from './usb-mode';

package/src/ports/README.md

@@ -1,61 +0,0 @@
-# Port contracts + ownership matrix
-
-The adapter boundaries `@ceralive/modem-control` reconciles across. Every concrete
-backend — the A2.3 fake harness, the A3.x ModemManager D-Bus backend, the A4.1
-`nmcli` NetworkManager adapter — implements one of these interfaces. Nothing here
-performs I/O; these are pure TypeScript contracts.
-
-## The ports
-
-| Port | File | Responsibility |
-|------|------|----------------|
-| `ModemObservationPort` | [`observation.ts`](./observation.ts) | Read-only: `start()`, `observe()`, `stop()`; emits discriminated `ObservationList` results that **retain rows** on source failure (removal is only ever an authoritative snapshot omission). |
-| `ModemManagerPort` | [`modem-manager.ts`](./modem-manager.ts) | **Extends** the observation port with the mutations MM owns: `setRadioModes`, `setPrimarySimSlot`, `sendPin`/`sendPuk`, `scanNetworks`, `inhibit`/`uninhibit`. **NO bearer/connect verb.** |
-| `NetworkManagerPort` | [`network-manager.ts`](./network-manager.ts) | GSM profile CRUD; `activate`/`deactivate` taking **both** `(connectionId, deviceIfname)`; quiesce lease. |
-| `RouterPort` | [`router.ts`](./router.ts) | Presence + advisory health only, for devices MM cannot control. |
-
-## Ownership matrix — one sole writer per resource
-
-Each resource below has **exactly one** owner. No other component writes it. This is
-the NM-owns-bearers architecture the whole package is built around (independent
-review correction, draft §Oracle #1): the controller is a reconciler over two
-adapters, never a second writer of the same resource.
-
-| Resource | Sole writer | Port / owner |
-|----------|-------------|--------------|
-| APN | NetworkManager | `NetworkManagerPort` (`gsm.apn` / auto-config) |
-| Connection auth (username / password) | NetworkManager | `NetworkManagerPort` (`gsm.username` / `gsm.password`) |
-| Roaming | NetworkManager | `NetworkManagerPort` (`gsm.home-only`) |
-| Autoconnect | NetworkManager | `NetworkManagerPort` (`connection.autoconnect`) |
-| Activation (bearer lifecycle) | NetworkManager | `NetworkManagerPort` (`activate`/`deactivate`) |
-| Radio access-technology modes | ModemManager | `ModemManagerPort.setRadioModes` |
-| SIM operations (PIN / PUK / primary slot / scan) | ModemManager | `ModemManagerPort` |
-| Recovery ladder | Local controller | policy `recovery` (disabled by default, A3.4) |
-| Usage policy (cycle / threshold) | Local controller | policy `usage` (A4.3 sampler) |
-
-### The bearer invariant (safety-critical)
-
-**The controller NEVER calls MM's `Simple.Connect`, `CreateBearer`, or
-`Bearer.Connect`.** Bearers, APN, and connection activation belong exclusively to
-NetworkManager. `ModemManagerPort` therefore has no `connect`, `createBearer`, or
-`bearerConnect` method, and none may ever be added. This is enforced at build time
-by [`forbidden-surface.test.ts`](./forbidden-surface.test.ts), which scans every
-port source file and fails if any bearer/connect method declaration appears.
-
-## Port-tagged ops
-
-The planner ([`reconcile.ts`](./reconcile.ts)) emits **port-tagged ops**
-([`ops.ts`](./ops.ts)): a discriminated union `{ port: 'mm', op: MmOp } | { port:
-'nm', op: NmOp }` whose op-kind spaces are disjoint. A radio op tagged for the NM
-port — `{ port: 'nm', op: { kind: 'setRadioModes', … } }` — is a **compile-time type
-error**, proved by [`ops.type-test.ts`](./ops.type-test.ts) (`@ts-expect-error`
-lines that `tsc --noEmit` must flag). The ownership matrix is thus enforced by the
-type system, not merely by convention.
-
-## Receipts
-
-Reconciliation is honest: each policy dimension yields exactly one
-[`Receipt`](./receipts.ts) with a status (`applied | pending | unsupported |
-failed`) and a **reason**. Nothing is silently dropped — "prefer 5G" on a 4G-only
-modem returns `unsupported` with an explicit reason, never a quiet downgrade to a
-4G-only mode.