@ceralive/modem-control 0.1.0

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@ceralive/modem-control",
+	"version": "0.1.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",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/CERALIVE/modem-stack.git",
+		"directory": "control"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org/",
+		"access": "public"
+	},
+	"exports": {
+		".": "./src/index.ts",
+		"./transport": "./src/transport/index.ts"
+	},
+	"files": [
+		"src"
+	],
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@httptoolkit/dbus-native": "0.1.5",
+		"zod": "4.4.3"
+	}
+}

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

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

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

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

package/src/backend/cell-info.ts

@@ -0,0 +1,160 @@
+// Cell-info normalization — a decoded ModemManager cell dict → a stable reading.
+//
+// `Modem.GetCellInfo` returns `aa{sv}`: one `a{sv}` dict per visible cell. The keys
+// vary by RAT and MM version, so this module pins EXACTLY the mappings the rest of
+// the stack depends on and ignores everything else:
+//
+//   - `physical-ci` → `pci`      (the real MM key; never guessed from anything else)
+//   - `rsrp`, `rsrq`             pass through as numbers
+//   - `sinr`                     the REAL NR SINR key. A dict carrying `snr` (the
+//                                WRONG name) is IGNORED — `sinr` stays undefined.
+//   - `cell-id`                  the cell identifier (serving-cell tiebreak)
+//   - `band`                     surfaced ONLY when the source supplies it directly;
+//                                never inferred from earfcn / frequency / anything.
+//   - `serving` / `cell-type`    whether this is the serving cell.
+//
+// Every reading also carries `source` + `observedAt` provenance, so a consumer can
+// tell a fresh reading from a cached one and know where it came from. Pure — no I/O.
+
+import type { EpochMillis } from '../domain';
+import type { DecodedProps } from './managed-objects';
+import { numberProp, stringProp } from './managed-objects';
+
+/** Where a batch of cell readings came from, and when it was observed. */
+export interface CellInfoProvenance {
+	/** A human/source tag, e.g. the modem path or `'Modem.GetCellInfo'`. */
+	readonly source: string;
+	readonly observedAt: EpochMillis;
+}
+
+/** One normalized cell reading — only the pinned fields, plus provenance. */
+export interface CellReading {
+	/** `true` when this dict is marked as the serving cell. */
+	readonly serving: boolean;
+	/** The cell identifier, when supplied (serving-cell tiebreak key). */
+	readonly cellId?: string;
+	/** Physical cell id — from the `physical-ci` key ONLY. */
+	readonly pci?: number;
+	readonly rsrp?: number;
+	readonly rsrq?: number;
+	/** NR SINR — from the `sinr` key ONLY (a `snr`-keyed dict is ignored). */
+	readonly sinr?: number;
+	/** Radio band — present ONLY when the source supplied it directly. */
+	readonly band?: string;
+	readonly source: string;
+	readonly observedAt: EpochMillis;
+}
+
+/** Read a `serving` flag: an explicit `serving` bool, else a `cell-type` naming it. */
+function readServing(cell: DecodedProps): boolean {
+	const flag = cell.find(([key]) => key === 'serving')?.[1]?.value;
+	if (typeof flag === 'boolean') {
+		return flag;
+	}
+	const cellType = stringProp(cell, 'cell-type');
+	return cellType?.toLowerCase().includes('serving') ?? false;
+}
+
+/** Normalize ONE cell's `a{sv}` dict into a `CellReading`, pinning the known keys. */
+export function normalizeCellReading(
+	cell: DecodedProps,
+	provenance: CellInfoProvenance,
+): CellReading {
+	const cellId = stringProp(cell, 'cell-id');
+	const pci = numberProp(cell, 'physical-ci');
+	const rsrp = numberProp(cell, 'rsrp');
+	const rsrq = numberProp(cell, 'rsrq');
+	// `sinr` ONLY — a dict carrying `snr` must never populate this field.
+	const sinr = numberProp(cell, 'sinr');
+	// `band` ONLY when directly supplied; never inferred.
+	const band = stringProp(cell, 'band');
+	return {
+		serving: readServing(cell),
+		...(cellId !== undefined ? { cellId } : {}),
+		...(pci !== undefined ? { pci } : {}),
+		...(rsrp !== undefined ? { rsrp } : {}),
+		...(rsrq !== undefined ? { rsrq } : {}),
+		...(sinr !== undefined ? { sinr } : {}),
+		...(band !== undefined ? { band } : {}),
+		source: provenance.source,
+		observedAt: provenance.observedAt,
+	};
+}
+
+/** Normalize a whole `GetCellInfo` reply (`aa{sv}` → cell dicts) into readings. */
+export function normalizeCellInfo(
+	cells: readonly DecodedProps[],
+	provenance: CellInfoProvenance,
+): readonly CellReading[] {
+	return cells.map((cell) => normalizeCellReading(cell, provenance));
+}
+
+/**
+ * Serving-cell TOTAL order — a strict, permutation-invariant ranking of readings.
+ * Returns < 0 when `a` outranks `b` (should sort first / is the better serving cell):
+ *
+ *   1. a `serving`-marked cell outranks a non-serving one;
+ *   2. then the HIGHER `rsrp` outranks the lower — a cell with NO `rsrp` sorts LAST;
+ *   3. ties break lexicographically by `cell-id` (a cell with none sorts last);
+ *   4. final deterministic tiebreaks (`pci`, then a stable serialization) guarantee
+ *      the order is total even for otherwise-identical distinct cells, so the winner
+ *      never depends on input order.
+ */
+export function compareServing(a: CellReading, b: CellReading): number {
+	if (a.serving !== b.serving) {
+		return a.serving ? -1 : 1;
+	}
+	const rsrpRank = compareOptionalDesc(a.rsrp, b.rsrp);
+	if (rsrpRank !== 0) {
+		return rsrpRank;
+	}
+	const cellRank = compareOptionalAsc(a.cellId, b.cellId);
+	if (cellRank !== 0) {
+		return cellRank;
+	}
+	const pciRank = compareOptionalAsc(a.pci, b.pci);
+	if (pciRank !== 0) {
+		return pciRank;
+	}
+	return stableTag(a) < stableTag(b) ? -1 : stableTag(a) > stableTag(b) ? 1 : 0;
+}
+
+/** Higher value first; `undefined` last. */
+function compareOptionalDesc(a: number | undefined, b: number | undefined): number {
+	if (a === b) return 0;
+	if (a === undefined) return 1;
+	if (b === undefined) return -1;
+	return b - a;
+}
+
+/** Lower value first; `undefined` last. Works for numbers and strings. */
+function compareOptionalAsc<T extends number | string>(a: T | undefined, b: T | undefined): number {
+	if (a === b) return 0;
+	if (a === undefined) return 1;
+	if (b === undefined) return -1;
+	return a < b ? -1 : 1;
+}
+
+/** A stable, order-independent fingerprint used only as the final total-order tiebreak. */
+function stableTag(reading: CellReading): string {
+	return JSON.stringify([
+		reading.serving,
+		reading.cellId ?? null,
+		reading.pci ?? null,
+		reading.rsrp ?? null,
+		reading.rsrq ?? null,
+		reading.sinr ?? null,
+		reading.band ?? null,
+	]);
+}
+
+/**
+ * Select the serving cell under the total order above. Permutation-invariant: the
+ * same set of readings always yields the same winner regardless of their order.
+ */
+export function selectServingCell(cells: readonly CellReading[]): CellReading | undefined {
+	if (cells.length === 0) {
+		return undefined;
+	}
+	return cells.reduce((best, cell) => (compareServing(cell, best) < 0 ? cell : best));
+}

package/src/backend/constants.ts

@@ -0,0 +1,35 @@
+// Well-known D-Bus names the ModemManager observer talks to.
+//
+// These mirror the real ModemManager bus topology. They are duplicated here (rather
+// than imported from the A2.3 test fake) on purpose: `control/test-support/` is not
+// published in the npm package, so `src` must never depend on it — the observer that
+// SHIPS owns its own copy of the constants it needs.
+
+/** The well-known bus name ModemManager owns. */
+export const MM_BUS_NAME = 'org.freedesktop.ModemManager1';
+
+/** The root ObjectManager object path. */
+export const MM_ROOT_PATH = '/org/freedesktop/ModemManager1';
+
+/** `org.freedesktop.DBus.ObjectManager` — `GetManagedObjects`, `InterfacesAdded/Removed`. */
+export const OBJECT_MANAGER_IFACE = 'org.freedesktop.DBus.ObjectManager';
+
+/** `org.freedesktop.DBus.Properties` — `PropertiesChanged`. */
+export const PROPERTIES_IFACE = 'org.freedesktop.DBus.Properties';
+
+/** The root manager interface — `InhibitDevice`, `ScanDevices`, `Version`. */
+export const MM_MANAGER_IFACE = 'org.freedesktop.ModemManager1';
+
+/** The core `Modem` interface. */
+export const MODEM_IFACE = 'org.freedesktop.ModemManager1.Modem';
+
+/** The separate `Modem.Modem3gpp` interface (never merged into `Modem`). */
+export const MODEM3GPP_IFACE = 'org.freedesktop.ModemManager1.Modem.Modem3gpp';
+
+/** A SIM object's `Sim` interface (SIMs are separate `/SIM/<n>` objects). */
+export const SIM_IFACE = 'org.freedesktop.ModemManager1.Sim';
+
+/** The bus daemon itself — `NameOwnerChanged`, `GetNameOwner`. */
+export const DBUS_IFACE = 'org.freedesktop.DBus';
+export const DBUS_PATH = '/org/freedesktop/DBus';
+export const DBUS_DESTINATION = 'org.freedesktop.DBus';