@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/ussd/session.js

@@ -0,0 +1,163 @@
+// The USSD session state machine — pure, total, and the only place a session's
+// legality is decided.
+//
+// USSD is a SESSION protocol, not a request/response one: `Initiate` opens a
+// dialogue the network may keep open pending a `Respond`, and a session that is
+// neither responded to nor cancelled stays open on the NETWORK side, consuming a
+// scarce per-subscriber slot and blocking the next `Initiate` with a busy error.
+// So "which verb is legal right now" is a real question with a real wrong answer,
+// and answering it inside the D-Bus adapter would make it untestable without a
+// bus. It lives here instead, as data.
+//
+// Everything the machine can be told is an EVENT and every answer is a
+// TRANSITION — an illegal verb is REFUSED with a typed reason, never thrown and
+// never silently ignored. A refusal at an RPC boundary must name what the caller
+// can do about it; a throw becomes an opaque failure and a silent no-op becomes a
+// UI that spins forever.
+//
+// The machine carries NO carrier text. The reply an operator sees is threaded by
+// the adapter and redacted at every log boundary (`../redact`); keeping it out of
+// the state entirely means a state snapshot can never leak one.
+/**
+ * Session states.
+ *
+ * Three of them (`idle`, `active`, `awaiting-reply`) mirror MM's own
+ * `MMModem3gppUssdSessionState`; the rest are LOCAL in-flight states, because MM
+ * has no state for "we dispatched a call and the reply has not landed". Without
+ * them a second `initiate` racing the first would be judged against `idle` and
+ * allowed through, which is exactly the double-open the network answers busy.
+ */
+export const USSD_SESSION_STATES = [
+    /** No session. MM `IDLE`. */
+    'idle',
+    /** `Initiate` dispatched, reply outstanding. Local. */
+    'initiating',
+    /** Network answered and the session is open with nothing pending. MM `ACTIVE`. */
+    'active',
+    /** Network asked a question; a `Respond` is required. MM `USER_RESPONSE`. */
+    'awaiting-reply',
+    /** `Respond` dispatched, reply outstanding. Local. */
+    'responding',
+    /** `Cancel` dispatched, confirmation outstanding. Local. */
+    'cancelling',
+    /** Terminal for this session object. A new session starts from a new machine. */
+    'closed',
+];
+/** How a session that reached `closed` got there. */
+export const USSD_SESSION_OUTCOMES = [
+    /** The network completed the dialogue and released the session. */
+    'completed',
+    /** The operator cancelled it. */
+    'cancelled',
+    /** No answer within the bound; the machine closed it locally. */
+    'timed-out',
+    /** The network or the modem refused. `refusal` names which. */
+    'failed',
+];
+export const IDLE_SESSION = { state: 'idle' };
+/** States in which an operator verb may be dispatched at all. */
+const ACCEPTS_INITIATE = new Set(['idle']);
+const ACCEPTS_RESPOND = new Set([
+    'awaiting-reply',
+]);
+const ACCEPTS_CANCEL = new Set([
+    'initiating',
+    'active',
+    'awaiting-reply',
+    'responding',
+]);
+/** States with a call in flight — the only ones a network answer may land on. */
+const IN_FLIGHT = new Set([
+    'initiating',
+    'responding',
+]);
+function open(state) {
+    return { ok: true, snapshot: { state } };
+}
+function close(outcome, refusal) {
+    return {
+        ok: true,
+        snapshot: { state: 'closed', outcome, ...(refusal === undefined ? {} : { refusal }) },
+    };
+}
+function refuse(refusal) {
+    return { ok: false, refusal };
+}
+/**
+ * Apply one event. TOTAL: every (state, event) pair has an answer, and an answer
+ * is either a new snapshot or a typed refusal that leaves the machine untouched.
+ *
+ * A `closed` machine accepts NOTHING — not even another `cancel`. Re-opening a
+ * terminal session would hide the fact that the previous one ended, and the
+ * cost of a fresh machine is one object.
+ */
+export function reduceUssdSession(snapshot, event) {
+    const state = snapshot.state;
+    if (state === 'closed') {
+        return refuse('no-session');
+    }
+    // Every event except `initiate` describes something happening TO a session,
+    // and an idle machine has none for them to happen to.
+    const sessionOpen = state !== 'idle';
+    switch (event.kind) {
+        case 'initiate':
+            // A session already in flight or open is the busy case the network
+            // itself would answer — refused locally so no second dialogue is opened.
+            return ACCEPTS_INITIATE.has(state) ? open('initiating') : refuse('session-busy');
+        case 'respond':
+            // Responding to a session that never asked a question is not a busy
+            // device; it is the wrong verb, and `invalid-state` says so.
+            return ACCEPTS_RESPOND.has(state) ? open('responding') : refuse('invalid-state');
+        case 'cancel':
+            // The two refusals are different operator facts: nothing to close, vs a
+            // cancel that is already in flight.
+            if (ACCEPTS_CANCEL.has(state)) {
+                return open('cancelling');
+            }
+            return refuse(sessionOpen ? 'invalid-state' : 'no-session');
+        case 'replied':
+            // A network answer that lands on a state with no call in flight is
+            // evidence of a lost reply or a duplicate; it is refused rather than
+            // used to resurrect a session the machine already moved past.
+            if (!IN_FLIGHT.has(state)) {
+                return refuse('invalid-state');
+            }
+            // The three-way answer is the dialogue-vs-one-shot distinction, and
+            // collapsing `active` into `released` is what would leave a session MM
+            // still considers open dangling on the network side.
+            if (event.sessionState === 'released') {
+                return close('completed');
+            }
+            return open(event.sessionState);
+        case 'cancelled':
+            // Only a machine that asked to cancel may be closed by one, so a stray
+            // confirmation cannot tear down a live dialogue.
+            return state === 'cancelling' ? close('cancelled') : refuse('invalid-state');
+        case 'network-released':
+            // The network is authoritative about its own session, so this lands
+            // from anywhere the session is still open — including mid-call, where
+            // it is the honest end of a dialogue whose reply will not come. During
+            // a cancel it is reported as `cancelled`: the operator asked for the
+            // session to end and it ended.
+            if (!sessionOpen) {
+                return refuse('no-session');
+            }
+            return close(state === 'cancelling' ? 'cancelled' : 'completed');
+        case 'timeout':
+            // The bound closes rather than reverting: after an unanswered call the
+            // network's own view is unknown, and pretending we are back at `idle`
+            // would let the next `initiate` walk into a busy error with no
+            // explanation.
+            return sessionOpen ? close('timed-out') : refuse('no-session');
+        case 'failed':
+            return sessionOpen ? close('failed', event.reason) : refuse('no-session');
+        default: {
+            const unreachable = event;
+            return unreachable;
+        }
+    }
+}
+/** True while the session still holds a network dialogue open. */
+export function isUssdSessionOpen(snapshot) {
+    return snapshot.state !== 'idle' && snapshot.state !== 'closed';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ceralive/modem-control",
-	"version": "1.0.0",
+	"version": "1.2.0",
 	"type": "module",
 	"description": "Cellular modem control for CeraLive — ModemManager D-Bus backend, NetworkManager adapter, desired-state reconciler, USB composition-mode model, data-usage sampler.",
 	"license": "AGPL-3.0",
@@ -13,14 +13,48 @@
 		"registry": "https://registry.npmjs.org/",
 		"access": "public"
 	},
+	"sideEffects": false,
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"exports": {
-		".": "./src/index.ts",
-		"./transport": "./src/transport/index.ts"
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./transport": {
+			"types": "./dist/transport/index.d.ts",
+			"import": "./dist/transport/index.js"
+		},
+		"./domain": {
+			"types": "./dist/domain/index.d.ts",
+			"import": "./dist/domain/index.js"
+		},
+		"./providers": {
+			"types": "./dist/providers/index.d.ts",
+			"import": "./dist/providers/index.js"
+		},
+		"./capabilities": {
+			"types": "./dist/capability/index.d.ts",
+			"import": "./dist/capability/index.js"
+		},
+		"./hardware": {
+			"types": "./dist/hardware/index.d.ts",
+			"import": "./dist/hardware/index.js"
+		},
+		"./testing": {
+			"types": "./dist/testing/index.d.ts",
+			"import": "./dist/testing/index.js"
+		},
+		"./package.json": "./package.json"
 	},
 	"files": [
-		"src"
+		"dist"
 	],
 	"scripts": {
+		"build": "bun run scripts/build.ts",
+		"prepack": "bun run build",
+		"verify:consumers": "bun run scripts/verify-consumers.ts",
+		"verify:tarball": "bun run scripts/assert-tarball-shape.ts",
 		"test": "bun test",
 		"typecheck": "tsc --noEmit"
 	},

package/src/backend/at-lease.test.ts

@@ -1,106 +0,0 @@
-// The AT lease's three guarantees: the allowlist rejects anything but ATI + catalog
-// commands (and never touches the sender when it does); the watchdog fires + rejects
-// a hung command; every attempt is audited through `redact`, so a secret in the
-// context is stripped before it is stored.
-
-import { describe, expect, test } from 'bun:test';
-import {
-	AT_BASELINE_ALLOWLIST,
-	AtCommandLease,
-	AtCommandNotAllowedError,
-	type AtCommandSender,
-	AtCommandTimeoutError,
-	type AtResponse,
-	computeAtAllowlist,
-} from './at-lease';
-
-const CATALOG_COMMAND = 'AT+QCFG="usbnet",2';
-
-function recordingSender(): { sender: AtCommandSender; sent: string[] } {
-	const sent: string[] = [];
-	return {
-		sent,
-		sender: {
-			send(command: string): Promise<AtResponse> {
-				sent.push(command);
-				return Promise.resolve({ ok: true, raw: 'OK' });
-			},
-		},
-	};
-}
-
-describe('AtCommandLease — allowlist', () => {
-	test('the baseline allowlist is exactly {ATI}; catalog commands union in', () => {
-		expect([...AT_BASELINE_ALLOWLIST]).toEqual(['ATI']);
-		const allowlist = computeAtAllowlist([CATALOG_COMMAND]);
-		expect(allowlist.has('ATI')).toBe(true);
-		expect(allowlist.has(CATALOG_COMMAND)).toBe(true);
-	});
-
-	test('ATI and the catalog command are allowed', async () => {
-		const { sender, sent } = recordingSender();
-		const lease = new AtCommandLease({ sender, allowlist: computeAtAllowlist([CATALOG_COMMAND]) });
-		await lease.run('ATI');
-		await lease.run(CATALOG_COMMAND);
-		expect(sent).toEqual(['ATI', CATALOG_COMMAND]);
-	});
-
-	test('a command outside the allowlist is rejected WITHOUT touching the sender', async () => {
-		const { sender, sent } = recordingSender();
-		const lease = new AtCommandLease({ sender, allowlist: computeAtAllowlist([CATALOG_COMMAND]) });
-		await expect(lease.run('AT+DANGEROUS')).rejects.toBeInstanceOf(AtCommandNotAllowedError);
-		expect(sent).toEqual([]);
-	});
-});
-
-describe('AtCommandLease — watchdog', () => {
-	test('a hung command fires the watchdog and rejects with a timeout', async () => {
-		const hangingSender: AtCommandSender = { send: () => new Promise<AtResponse>(() => undefined) };
-		const watchdogHits: string[] = [];
-		const lease = new AtCommandLease({
-			sender: hangingSender,
-			allowlist: computeAtAllowlist([]),
-			timeoutMs: 20,
-			onWatchdog: (command) => {
-				watchdogHits.push(command);
-			},
-		});
-		await expect(lease.run('ATI')).rejects.toBeInstanceOf(AtCommandTimeoutError);
-		expect(watchdogHits).toEqual(['ATI']);
-	});
-});
-
-describe('AtCommandLease — audit + redaction', () => {
-	test('a sensitive value in the audit context is redacted before recording', async () => {
-		const { sender } = recordingSender();
-		const entries: unknown[] = [];
-		const lease = new AtCommandLease({
-			sender,
-			allowlist: computeAtAllowlist([]),
-			audit: { record: (entry) => entries.push(entry) },
-		});
-		await lease.run('ATI', { subscriptionId: 'SECRET-ICCID', note: 'keep-me' });
-		expect(entries).toHaveLength(1);
-		const recorded = entries[0] as {
-			command: string;
-			outcome: string;
-			context: Record<string, unknown>;
-		};
-		expect(recorded.command).toBe('ATI');
-		expect(recorded.outcome).toBe('sent');
-		expect(recorded.context.subscriptionId).toBe('[redacted]');
-		expect(recorded.context.note).toBe('keep-me');
-	});
-
-	test('a rejected command is audited with outcome "rejected"', async () => {
-		const { sender } = recordingSender();
-		const entries: Array<{ outcome: string }> = [];
-		const lease = new AtCommandLease({
-			sender,
-			allowlist: computeAtAllowlist([]),
-			audit: { record: (entry) => entries.push(entry as { outcome: string }) },
-		});
-		await expect(lease.run('AT+NOPE')).rejects.toBeInstanceOf(AtCommandNotAllowedError);
-		expect(entries[0]?.outcome).toBe('rejected');
-	});
-});

package/src/backend/at-lease.ts

@@ -1,158 +0,0 @@
-// The AT-command lease baseline — the ONLY channel raw AT commands may travel.
-//
-// Three non-negotiable safety properties (draft §rounds 5/6, §84 raw-AT lease):
-//   1. ALLOWLIST — only `ATI` (identify) plus the exact commands a certified catalog
-//      entry declares may ever be sent. Anything else is rejected BEFORE the sender
-//      is touched. There is no escape hatch.
-//   2. WATCHDOG — a command that does not return within the timeout fires the
-//      `onWatchdog` hook (the transition wires this to force-uninhibit) and rejects,
-//      so a hung AT write can never wedge the transaction forever.
-//   3. AUDIT + REDACTION — every attempt is recorded through A2.2's `redact` (never a
-//      reimplementation), so an identifier that lands in an audit entry's context is
-//      stripped before it is stored.
-
-import { type EpochMillis, epochMillis } from '../domain';
-import { redact } from '../redact';
-
-/** The baseline allowlist — identify only. Catalog commands are unioned in per SKU. */
-export const AT_BASELINE_ALLOWLIST: ReadonlySet<string> = new Set(['ATI']);
-
-/** Union the baseline allowlist with a catalog entry's declared transition commands. */
-export function computeAtAllowlist(commands: Iterable<string>): ReadonlySet<string> {
-	return new Set<string>([...AT_BASELINE_ALLOWLIST, ...commands]);
-}
-
-/** An AT command's response. `ok` (an `OK` terminator) is NEVER transition-success alone. */
-export interface AtResponse {
-	readonly ok: boolean;
-	readonly raw: string;
-}
-
-/** The raw AT transport — a serial write, injected so tests need no hardware. */
-export interface AtCommandSender {
-	send(command: string): Promise<AtResponse>;
-}
-
-/** One audited AT attempt. Recorded only after passing through `redact`. */
-export interface AtAuditEntry {
-	readonly command: string;
-	readonly outcome: 'sent' | 'rejected' | 'timeout' | 'error';
-	readonly at: EpochMillis;
-	readonly ok?: boolean;
-	readonly reason?: string;
-	readonly context?: Record<string, unknown>;
-}
-
-/** Where audit entries go — receives a REDACTED copy of each `AtAuditEntry`. */
-export interface AtAuditSink {
-	record(entry: unknown): void;
-}
-
-/** Thrown when a command outside the allowlist is attempted — the sender is never called. */
-export class AtCommandNotAllowedError extends Error {
-	constructor(command: string) {
-		super(`AT command not in allowlist: ${command}`);
-		this.name = 'AtCommandNotAllowedError';
-		Object.setPrototypeOf(this, AtCommandNotAllowedError.prototype);
-	}
-}
-
-/** Thrown when a command exceeds the watchdog timeout. */
-export class AtCommandTimeoutError extends Error {
-	constructor(command: string, timeoutMs: number) {
-		super(`AT command timed out after ${timeoutMs}ms: ${command}`);
-		this.name = 'AtCommandTimeoutError';
-		Object.setPrototypeOf(this, AtCommandTimeoutError.prototype);
-	}
-}
-
-/** Construction dependencies for an `AtCommandLease`. */
-export interface AtCommandLeaseDeps {
-	readonly sender: AtCommandSender;
-	readonly allowlist: ReadonlySet<string>;
-	readonly audit?: AtAuditSink;
-	readonly now?: () => EpochMillis;
-	readonly timeoutMs?: number;
-	/** Fired when a command exceeds the timeout — the transition wires force-uninhibit here. */
-	readonly onWatchdog?: (command: string) => void | Promise<void>;
-}
-
-const DEFAULT_AT_TIMEOUT_MS = 10_000;
-
-/**
- * A held AT-command lease. `run` enforces the allowlist, bounds the send with a
- * watchdog, and audits every attempt (redacted). The allowlist is fixed at
- * construction from `computeAtAllowlist(entry)`, so a lease can only ever emit the
- * commands one certified SKU permits.
- */
-export class AtCommandLease {
-	readonly #sender: AtCommandSender;
-	readonly #allowlist: ReadonlySet<string>;
-	readonly #audit: AtAuditSink | undefined;
-	readonly #now: () => EpochMillis;
-	readonly #timeoutMs: number;
-	readonly #onWatchdog: ((command: string) => void | Promise<void>) | undefined;
-
-	constructor(deps: AtCommandLeaseDeps) {
-		this.#sender = deps.sender;
-		this.#allowlist = deps.allowlist;
-		this.#audit = deps.audit;
-		this.#now = deps.now ?? ((): EpochMillis => epochMillis(Date.now()));
-		this.#timeoutMs = deps.timeoutMs ?? DEFAULT_AT_TIMEOUT_MS;
-		this.#onWatchdog = deps.onWatchdog;
-	}
-
-	/** Send one AT command through the lease. `context` is redacted into the audit entry. */
-	async run(command: string, context?: Record<string, unknown>): Promise<AtResponse> {
-		const ctx = context !== undefined ? { context } : {};
-		if (!this.#allowlist.has(command)) {
-			this.#record({
-				command,
-				outcome: 'rejected',
-				at: this.#now(),
-				reason: 'not in allowlist',
-				...ctx,
-			});
-			throw new AtCommandNotAllowedError(command);
-		}
-		try {
-			const response = await this.#sendWithWatchdog(command);
-			this.#record({ command, outcome: 'sent', at: this.#now(), ok: response.ok, ...ctx });
-			return response;
-		} catch (error) {
-			const timedOut = error instanceof AtCommandTimeoutError;
-			if (timedOut) {
-				await this.#onWatchdog?.(command);
-			}
-			this.#record({
-				command,
-				outcome: timedOut ? 'timeout' : 'error',
-				at: this.#now(),
-				reason: error instanceof Error ? error.message : String(error),
-				...ctx,
-			});
-			throw error;
-		}
-	}
-
-	async #sendWithWatchdog(command: string): Promise<AtResponse> {
-		let timer: ReturnType<typeof setTimeout> | undefined;
-		const watchdog = new Promise<never>((_, reject) => {
-			timer = setTimeout(
-				() => reject(new AtCommandTimeoutError(command, this.#timeoutMs)),
-				this.#timeoutMs,
-			);
-		});
-		try {
-			return await Promise.race([this.#sender.send(command), watchdog]);
-		} finally {
-			if (timer !== undefined) {
-				clearTimeout(timer);
-			}
-		}
-	}
-
-	#record(entry: AtAuditEntry): void {
-		this.#audit?.record(redact(entry));
-	}
-}

package/src/backend/cell-info.test.ts

@@ -1,154 +0,0 @@
-// Cell-info normalization — pure fixtures, no bus.
-//
-// Locks the review-corrected mappings (draft round 10/11): the real NR key is `sinr`
-// (a `snr`-carrying dict is IGNORED), `physical-ci` → `pci`, `rsrp`/`rsrq` pass
-// through, `band` only when directly supplied, provenance is always carried, and the
-// serving-cell TOTAL order is permutation-invariant.
-
-import { describe, expect, test } from 'bun:test';
-import { epochMillis } from '../domain';
-import type { DbusVariant } from '../transport';
-import { type CellReading, normalizeCellReading, selectServingCell } from './cell-info';
-import type { DecodedProps } from './managed-objects';
-
-type Scalar = number | string | boolean;
-
-function v(value: Scalar): DbusVariant {
-	const signature = typeof value === 'number' ? 'i' : typeof value === 'boolean' ? 'b' : 's';
-	return { signature, value };
-}
-
-function cell(record: Record<string, Scalar>): DecodedProps {
-	return Object.entries(record).map(([key, value]) => [key, v(value)] as const);
-}
-
-const PROVENANCE = {
-	source: '/org/freedesktop/ModemManager1/Modem/0',
-	observedAt: epochMillis(1000),
-};
-
-const read = (record: Record<string, Scalar>): CellReading =>
-	normalizeCellReading(cell(record), PROVENANCE);
-
-/** Every fixed permutation of a small array — exhaustive, deterministic shuffle. */
-function permutations<T>(items: readonly T[]): T[][] {
-	if (items.length <= 1) {
-		return [[...items]];
-	}
-	const result: T[][] = [];
-	items.forEach((item, index) => {
-		const rest = [...items.slice(0, index), ...items.slice(index + 1)];
-		for (const tail of permutations(rest)) {
-			result.push([item, ...tail]);
-		}
-	});
-	return result;
-}
-
-describe('normalizeCellReading — pinned key mappings', () => {
-	test('the real NR key is `sinr`', () => {
-		expect(read({ sinr: 12 }).sinr).toBe(12);
-	});
-
-	test('a `snr`-carrying dict is IGNORED — sinr stays undefined', () => {
-		const reading = read({ snr: 9, rsrp: -95 });
-		expect(reading.sinr).toBeUndefined();
-		expect(reading.rsrp).toBe(-95);
-	});
-
-	test('`sinr` wins even when `snr` is also present (wrong key never leaks in)', () => {
-		expect(read({ snr: 9, sinr: 12 }).sinr).toBe(12);
-	});
-
-	test('`physical-ci` maps to `pci`; rsrp/rsrq pass through', () => {
-		const reading = read({ 'physical-ci': 42, rsrp: -95, rsrq: -10 });
-		expect(reading.pci).toBe(42);
-		expect(reading.rsrp).toBe(-95);
-		expect(reading.rsrq).toBe(-10);
-	});
-
-	test('`band` is surfaced ONLY when directly supplied', () => {
-		expect(read({ rsrp: -90 }).band).toBeUndefined();
-		expect(read({ rsrp: -90, band: 'n78' }).band).toBe('n78');
-	});
-
-	test('every reading carries `source` + `observedAt` provenance', () => {
-		const reading = read({ 'cell-id': 'A', rsrp: -80 });
-		expect(reading.source).toBe(PROVENANCE.source);
-		expect(reading.observedAt).toBe(PROVENANCE.observedAt);
-	});
-
-	test('serving flag reads a `serving` bool OR a serving `cell-type`', () => {
-		expect(read({ serving: true }).serving).toBe(true);
-		expect(read({ 'cell-type': 'lte-serving' }).serving).toBe(true);
-		expect(read({ 'cell-type': 'lte-neighbor' }).serving).toBe(false);
-	});
-});
-
-describe('selectServingCell — TOTAL order', () => {
-	test('a serving-marked cell wins even with a LOWER rsrp', () => {
-		const marked = read({ 'cell-id': 'A', serving: true, rsrp: -110 });
-		const strong = read({ 'cell-id': 'B', rsrp: -70 });
-		expect(selectServingCell([strong, marked])?.cellId).toBe('A');
-	});
-
-	test('with no serving mark, the HIGHEST rsrp wins', () => {
-		const cells = [
-			read({ 'cell-id': 'A', rsrp: -95 }),
-			read({ 'cell-id': 'B', rsrp: -70 }),
-			read({ 'cell-id': 'C', rsrp: -110 }),
-		];
-		expect(selectServingCell(cells)?.cellId).toBe('B');
-	});
-
-	test('cells lacking rsrp sort LAST', () => {
-		const withRsrp = read({ 'cell-id': 'A', rsrp: -120 });
-		const noRsrp = read({ 'cell-id': 'B' });
-		expect(selectServingCell([noRsrp, withRsrp])?.cellId).toBe('A');
-	});
-
-	test('an rsrp tie breaks lexicographically by cell-id', () => {
-		const cells = [
-			read({ 'cell-id': 'zeta', rsrp: -80 }),
-			read({ 'cell-id': 'alpha', rsrp: -80 }),
-			read({ 'cell-id': 'mike', rsrp: -80 }),
-		];
-		expect(selectServingCell(cells)?.cellId).toBe('alpha');
-	});
-
-	test('empty input has no serving cell', () => {
-		expect(selectServingCell([])).toBeUndefined();
-	});
-});
-
-describe('selectServingCell — permutation invariance (MANDATORY)', () => {
-	test('every permutation of a mixed cell set picks the SAME serving cell', () => {
-		const cells = [
-			read({ 'cell-id': 'A', rsrp: -95, 'physical-ci': 1 }),
-			read({ 'cell-id': 'B', serving: true, rsrp: -108, 'physical-ci': 2 }),
-			read({ 'cell-id': 'C', rsrp: -70, 'physical-ci': 3 }),
-			read({ 'cell-id': 'D', 'physical-ci': 4 }),
-			read({ 'cell-id': 'E', rsrp: -88, 'physical-ci': 5 }),
-		];
-		const perms = permutations(cells);
-		expect(perms.length).toBe(120);
-		// The serving-marked cell B wins regardless of order.
-		for (const perm of perms) {
-			expect(selectServingCell(perm)?.cellId).toBe('B');
-		}
-	});
-
-	test('without a serving mark, the highest-rsrp winner is permutation-invariant', () => {
-		const cells = [
-			read({ 'cell-id': 'A', rsrp: -95 }),
-			read({ 'cell-id': 'B', rsrp: -70 }),
-			read({ 'cell-id': 'C', rsrp: -110 }),
-			read({ 'cell-id': 'D', rsrp: -70 }),
-			read({ 'cell-id': 'E' }),
-		];
-		// Tie at -70 between B and D → lexicographic → B.
-		for (const perm of permutations(cells)) {
-			expect(selectServingCell(perm)?.cellId).toBe('B');
-		}
-	});
-});