@ceralive/modem-control 0.1.0

package/src/ports/ops.type-test.ts

@@ -0,0 +1,39 @@
+// COMPILE-TIME negative tests for port-tagged op disjointness.
+//
+// This file is type-checked by `tsc --noEmit` (it is inside the workspace
+// `include`) but is NOT a runtime test — it is never imported and every binding is
+// a type assertion. Each `@ts-expect-error` asserts the type system REJECTS a
+// mis-tagged op; if disjointness ever regresses (e.g. an `NmOp` gains a radio
+// `kind`), the directive becomes UNUSED and `tsc` fails the build. That failure IS
+// the ownership matrix enforced at the type level.
+
+import { connectionId, deviceIfname } from './network-manager';
+import type { MmOp, NmOp, PortTaggedOp } from './ops';
+
+const radioOp: MmOp = { kind: 'setRadioModes', preference: { preferenceOrdered: ['5gnr'] } };
+const slotOp: MmOp = { kind: 'setPrimarySimSlot', slotIndex: 2 };
+const activateOp: NmOp = {
+	kind: 'activate',
+	connectionId: connectionId('11111111-1111-1111-1111-111111111111'),
+	deviceIfname: deviceIfname('wwan0'),
+};
+
+// Positive controls — correctly-tagged ops MUST type-check.
+const goodMm: PortTaggedOp = { port: 'mm', op: radioOp };
+const goodNm: PortTaggedOp = { port: 'nm', op: activateOp };
+
+// @ts-expect-error a radio op tagged for the NM port must NOT compile.
+const badRadioOnNm: PortTaggedOp = { port: 'nm', op: radioOp };
+// @ts-expect-error a SIM op tagged for the NM port must NOT compile.
+const badSlotOnNm: PortTaggedOp = { port: 'nm', op: slotOp };
+// @ts-expect-error an activate op tagged for the MM port must NOT compile.
+const badActivateOnMm: PortTaggedOp = { port: 'mm', op: activateOp };
+
+// Exported so the bindings are "used" and lint stays quiet; never imported at runtime.
+export const PORT_TAGGED_OP_TYPE_CASES: readonly PortTaggedOp[] = [
+	goodMm,
+	goodNm,
+	badRadioOnNm,
+	badSlotOnNm,
+	badActivateOnMm,
+];

package/src/ports/receipts.test.ts

@@ -0,0 +1,153 @@
+// Receipt taxonomy — every status reachable, "prefer 5G on 4G-only" is surfaced as
+// `unsupported` (never silently downgraded), and every receipt carries a reason.
+
+import { expect, test } from 'bun:test';
+import {
+	type DesiredCellularPolicy,
+	defaultCellularPolicy,
+	imeiEquipmentId,
+	type PolicyBindingKey,
+	policyBindingKey,
+	runtimePath,
+} from '../domain';
+import { connectionId, deviceIfname } from './network-manager';
+import type { PolicyDimension, Receipt } from './receipts';
+import { type AppliedCellularState, type ModemCapabilities, planReconcile } from './reconcile';
+
+const BOUND_TO: PolicyBindingKey = policyBindingKey({
+	equipmentId: imeiEquipmentId('490154203237518'),
+	runtimePath: runtimePath('/org/freedesktop/ModemManager1/Modem/0'),
+});
+
+const FOUR_G_ONLY: ModemCapabilities = {
+	supportedRats: new Set(['lte', 'umts', 'gsm']),
+	simSlotCount: 1,
+	supportsAutoApn: true,
+};
+
+const FIVE_G_DUAL_SLOT: ModemCapabilities = {
+	supportedRats: new Set(['5gnr', 'lte', 'umts', 'gsm']),
+	simSlotCount: 2,
+	supportsAutoApn: true,
+};
+
+const ADDRESSABLE = {
+	connectionId: connectionId('conn-uuid'),
+	deviceIfname: deviceIfname('wwan0'),
+	appliedApn: 'auto',
+	appliedRoaming: false,
+	appliedRadioPreference: ['5gnr', 'lte', 'umts', 'gsm'],
+} as const;
+
+function receiptFor(receipts: readonly Receipt[], dimension: PolicyDimension): Receipt {
+	const found = receipts.find((entry) => entry.dimension === dimension);
+	if (found === undefined) {
+		throw new Error(`no receipt for dimension ${dimension}`);
+	}
+	return found;
+}
+
+test('prefer 5G on a 4G-only modem is unsupported with a reason, never silently applied', () => {
+	const policy = defaultCellularPolicy(BOUND_TO);
+	const applied: AppliedCellularState = { nmActivation: 'disconnected', hasProfile: false };
+	const { ops, receipts } = planReconcile(applied, policy, FOUR_G_ONLY);
+
+	const radio = receiptFor(receipts, 'radio');
+	expect(radio.status).toBe('unsupported');
+	expect(radio.reason).toContain('5gnr');
+	expect(radio.reason.length).toBeGreaterThan(0);
+	expect(ops.filter((op) => op.port === 'mm' && op.op.kind === 'setRadioModes')).toEqual([]);
+});
+
+test('all four receipt statuses are reachable', () => {
+	const policy = defaultCellularPolicy(BOUND_TO);
+
+	const applied: AppliedCellularState = {
+		nmActivation: 'activated',
+		hasProfile: true,
+		...ADDRESSABLE,
+	};
+	expect(
+		receiptFor(planReconcile(applied, policy, FIVE_G_DUAL_SLOT).receipts, 'enabled').status,
+	).toBe('applied');
+
+	const pending: AppliedCellularState = {
+		nmActivation: 'disconnected',
+		hasProfile: true,
+		...ADDRESSABLE,
+	};
+	expect(
+		receiptFor(planReconcile(pending, policy, FIVE_G_DUAL_SLOT).receipts, 'enabled').status,
+	).toBe('pending');
+
+	const unsupported: AppliedCellularState = { nmActivation: 'disconnected', hasProfile: false };
+	expect(receiptFor(planReconcile(unsupported, policy, FOUR_G_ONLY).receipts, 'radio').status).toBe(
+		'unsupported',
+	);
+
+	const failed: AppliedCellularState = {
+		nmActivation: 'failed',
+		hasProfile: true,
+		activationFailureReason: 'no-signal',
+		...ADDRESSABLE,
+	};
+	const failedReceipt = receiptFor(
+		planReconcile(failed, policy, FIVE_G_DUAL_SLOT).receipts,
+		'enabled',
+	);
+	expect(failedReceipt.status).toBe('failed');
+	expect(failedReceipt.reason).toContain('no-signal');
+});
+
+test('every dimension yields a receipt and every receipt has a non-empty reason', () => {
+	const policy = defaultCellularPolicy(BOUND_TO);
+	const { receipts } = planReconcile(
+		{ nmActivation: 'disconnected', hasProfile: false },
+		policy,
+		FOUR_G_ONLY,
+	);
+	for (const entry of receipts) {
+		expect(entry.reason.length).toBeGreaterThan(0);
+	}
+	const expectedDimensions: PolicyDimension[] = [
+		'connection',
+		'enabled',
+		'radio',
+		'recovery',
+		'roaming',
+		'simSlot',
+		'usage',
+	];
+	expect(receipts.map((entry) => entry.dimension).sort()).toEqual(expectedDimensions.sort());
+});
+
+test('primary SIM slot selection is unsupported on a single-slot modem', () => {
+	const policy: DesiredCellularPolicy = { ...defaultCellularPolicy(BOUND_TO), simSlot: 2 };
+	const { receipts } = planReconcile(
+		{ nmActivation: 'disconnected', hasProfile: false },
+		policy,
+		FOUR_G_ONLY,
+	);
+	expect(receiptFor(receipts, 'simSlot').status).toBe('unsupported');
+});
+
+test('an out-of-range primary SIM slot is a failed receipt', () => {
+	const policy: DesiredCellularPolicy = { ...defaultCellularPolicy(BOUND_TO), simSlot: 5 };
+	const { receipts } = planReconcile(
+		{ nmActivation: 'disconnected', hasProfile: false },
+		policy,
+		FIVE_G_DUAL_SLOT,
+	);
+	expect(receiptFor(receipts, 'simSlot').status).toBe('failed');
+});
+
+test('Auto-APN is unsupported when the stack cannot auto-configure', () => {
+	const policy = defaultCellularPolicy(BOUND_TO);
+	const caps: ModemCapabilities = { ...FIVE_G_DUAL_SLOT, supportsAutoApn: false };
+	const { receipts } = planReconcile(
+		{ nmActivation: 'disconnected', hasProfile: false },
+		policy,
+		caps,
+	);
+	expect(receiptFor(receipts, 'connection').status).toBe('unsupported');
+});

package/src/ports/receipts.ts

@@ -0,0 +1,43 @@
+// Reconcile receipts — the HONEST outcome of trying to apply one policy dimension.
+//
+// Every attempt to converge a dimension yields exactly one receipt with a status
+// AND a reason. Nothing is ever silently dropped: "prefer 5G" on a 4G-only modem is
+// reported as `unsupported` with a reason, never quietly downgraded to "5G off".
+
+/** The policy dimension a receipt is about. */
+export type PolicyDimension =
+	| 'enabled'
+	| 'connection'
+	| 'roaming'
+	| 'radio'
+	| 'simSlot'
+	| 'recovery'
+	| 'usage';
+
+/**
+ * Receipt status taxonomy:
+ *   - applied     — the desired state is in effect (converged, or already was).
+ *   - pending     — an op was issued; a terminal state is not yet observed.
+ *   - unsupported — the hardware / stack cannot honor this desire (surfaced, not silent).
+ *   - failed      — an op was attempted and errored.
+ */
+export type ReceiptStatus = 'applied' | 'pending' | 'unsupported' | 'failed';
+
+/**
+ * One reconcile receipt. `reason` is ALWAYS populated — a receipt with no reason
+ * would be a silent outcome, which the contract forbids.
+ */
+export interface Receipt {
+	readonly dimension: PolicyDimension;
+	readonly status: ReceiptStatus;
+	readonly reason: string;
+}
+
+/** Build a receipt. Kept as a helper so `reason` can never be forgotten. */
+export function receipt(
+	dimension: PolicyDimension,
+	status: ReceiptStatus,
+	reason: string,
+): Receipt {
+	return { dimension, status, reason };
+}

package/src/ports/reconcile.test.ts

@@ -0,0 +1,152 @@
+// Idempotent re-apply — a minimal in-memory stack executes the planner's
+// port-tagged ops; re-applying the same policy performs ZERO new side effects and
+// returns the same receipts. NOT the A2.3 fake D-Bus harness — just enough to prove
+// the pure planner converges to a fixpoint.
+
+import { expect, test } from 'bun:test';
+import {
+	type DesiredCellularPolicy,
+	defaultCellularPolicy,
+	imeiEquipmentId,
+	type PolicyBindingKey,
+	policyBindingKey,
+	runtimePath,
+} from '../domain';
+import { connectionId, deviceIfname } from './network-manager';
+import type { PortTaggedOp } from './ops';
+import type { Receipt } from './receipts';
+import { type AppliedCellularState, type ModemCapabilities, planReconcile } from './reconcile';
+
+const BOUND_TO: PolicyBindingKey = policyBindingKey({
+	equipmentId: imeiEquipmentId('490154203237518'),
+	runtimePath: runtimePath('/org/freedesktop/ModemManager1/Modem/0'),
+});
+
+const FIVE_G_DUAL_SLOT: ModemCapabilities = {
+	supportedRats: new Set(['5gnr', 'lte', 'umts', 'gsm']),
+	simSlotCount: 2,
+	supportsAutoApn: true,
+};
+
+const FOUR_G_ONLY: ModemCapabilities = {
+	supportedRats: new Set(['lte', 'umts', 'gsm']),
+	simSlotCount: 2,
+	supportsAutoApn: true,
+};
+
+class InMemoryStack {
+	private state: AppliedCellularState;
+	readonly executed: PortTaggedOp[] = [];
+
+	constructor(
+		initial: AppliedCellularState,
+		private readonly capabilities: ModemCapabilities,
+	) {
+		this.state = initial;
+	}
+
+	private execute(op: PortTaggedOp): void {
+		this.executed.push(op);
+		if (op.port === 'mm') {
+			this.state =
+				op.op.kind === 'setRadioModes'
+					? { ...this.state, appliedRadioPreference: op.op.preference.preferenceOrdered }
+					: { ...this.state, activePrimarySlot: op.op.slotIndex };
+			return;
+		}
+		switch (op.op.kind) {
+			case 'createGsmProfile':
+				this.state = {
+					...this.state,
+					hasProfile: true,
+					connectionId: connectionId('conn-generated'),
+					appliedApn: op.op.profile.autoConfig ? 'auto' : op.op.profile.apn,
+					appliedRoaming: !op.op.profile.homeOnly,
+				};
+				break;
+			case 'updateGsmProfile': {
+				const { patch } = op.op;
+				const nextApn = patch.autoConfig ? 'auto' : patch.apn;
+				this.state = {
+					...this.state,
+					...(nextApn !== undefined ? { appliedApn: nextApn } : {}),
+					...(patch.homeOnly !== undefined ? { appliedRoaming: !patch.homeOnly } : {}),
+				};
+				break;
+			}
+			case 'activate':
+				this.state = { ...this.state, nmActivation: 'activated' };
+				break;
+			case 'deactivate':
+				this.state = { ...this.state, nmActivation: 'disconnected' };
+				break;
+		}
+	}
+
+	apply(desired: DesiredCellularPolicy): readonly Receipt[] {
+		for (let iteration = 0; iteration < 20; iteration += 1) {
+			const plan = planReconcile(this.state, desired, this.capabilities);
+			if (plan.ops.length === 0) {
+				return plan.receipts;
+			}
+			for (const op of plan.ops) {
+				this.execute(op);
+			}
+		}
+		throw new Error('reconcile did not converge within the iteration budget');
+	}
+}
+
+function baseState(): AppliedCellularState {
+	return { nmActivation: 'disconnected', hasProfile: false, deviceIfname: deviceIfname('wwan0') };
+}
+
+test('a fresh policy converges, then re-apply does nothing and returns the same receipts', () => {
+	const stack = new InMemoryStack(baseState(), FIVE_G_DUAL_SLOT);
+	const policy = defaultCellularPolicy(BOUND_TO);
+
+	const first = stack.apply(policy);
+	const sideEffectsAfterFirst = stack.executed.length;
+	expect(sideEffectsAfterFirst).toBeGreaterThan(0);
+
+	const second = stack.apply(policy);
+	expect(stack.executed.length).toBe(sideEffectsAfterFirst);
+	expect(second).toEqual(first);
+
+	for (const entry of second) {
+		expect(entry.status).toBe('applied');
+	}
+});
+
+test('each op is executed exactly once across convergence (no double side-effects)', () => {
+	const stack = new InMemoryStack(baseState(), FIVE_G_DUAL_SLOT);
+	const policy = defaultCellularPolicy(BOUND_TO);
+	stack.apply(policy);
+
+	const kinds = stack.executed.map((op) => op.op.kind).sort();
+	expect(kinds).toEqual(['activate', 'createGsmProfile', 'setRadioModes']);
+});
+
+test('an unsupported dimension is never applied as an op, on the first apply or any re-apply', () => {
+	const stack = new InMemoryStack(baseState(), FOUR_G_ONLY);
+	const policy = defaultCellularPolicy(BOUND_TO);
+
+	const first = stack.apply(policy);
+	stack.apply(policy);
+
+	expect(stack.executed.some((op) => op.port === 'mm' && op.op.kind === 'setRadioModes')).toBe(
+		false,
+	);
+	expect(first.find((entry) => entry.dimension === 'radio')?.status).toBe('unsupported');
+});
+
+test('deactivation is idempotent — disabling an already-inactive connection is a no-op', () => {
+	const stack = new InMemoryStack(baseState(), FIVE_G_DUAL_SLOT);
+	const policy: DesiredCellularPolicy = { ...defaultCellularPolicy(BOUND_TO), enabled: false };
+
+	stack.apply(policy);
+	const sideEffects = stack.executed.length;
+	stack.apply(policy);
+	expect(stack.executed.length).toBe(sideEffects);
+	expect(stack.executed.some((op) => op.port === 'nm' && op.op.kind === 'activate')).toBe(false);
+});