@ceralive/modem-control 1.0.0 → 1.2.0

package/src/backend/features.test.ts

@@ -1,162 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import {
-	detectMmFeatures,
-	type MmPropertyProbe,
-	parseMmVersion,
-	probeModemProperties,
-} from './features';
-import type { DecodedManagedObjects } from './managed-objects';
-
-const BASE_MODEM_PROPS = new Set(['Manufacturer', 'Model', 'Device', 'State', 'SimType']);
-
-function probe(overrides: Partial<MmPropertyProbe> = {}): MmPropertyProbe {
-	return { properties: BASE_MODEM_PROPS, ...overrides };
-}
-
-function withPhysdev(): MmPropertyProbe {
-	return { properties: new Set([...BASE_MODEM_PROPS, 'Physdev']) };
-}
-
-describe('parseMmVersion', () => {
-	test('parses major.minor.patch', () => {
-		expect(parseMmVersion('1.24.0')).toEqual({ major: 1, minor: 24 });
-	});
-
-	test('parses the 1.24.2 FM350-fix release', () => {
-		expect(parseMmVersion('1.24.2')).toEqual({ major: 1, minor: 24 });
-	});
-
-	test('parses major.minor without a patch', () => {
-		expect(parseMmVersion('1.20')).toEqual({ major: 1, minor: 20 });
-	});
-
-	test('tolerates a pre-release suffix', () => {
-		expect(parseMmVersion('1.26.0-rc1')).toEqual({ major: 1, minor: 26 });
-	});
-
-	test('returns null for an unparseable string', () => {
-		expect(parseMmVersion('not-a-version')).toBeNull();
-	});
-});
-
-describe('detectMmFeatures — 3 property shapes', () => {
-	test('1.20 shape: no Physdev, basic cell info, eSIM, serialization', () => {
-		expect(detectMmFeatures('1.20.0', probe())).toEqual({
-			physdev: false,
-			cellInfo: 'basic',
-			esimStatus: true,
-			opSerialization: true,
-		});
-	});
-
-	test('1.22 shape: Physdev present, rich cell info', () => {
-		expect(detectMmFeatures('1.22.0', withPhysdev())).toEqual({
-			physdev: true,
-			cellInfo: 'rich',
-			esimStatus: true,
-			opSerialization: true,
-		});
-	});
-
-	test('1.24 shape: Physdev present, rich cell info', () => {
-		expect(detectMmFeatures('1.24.0', withPhysdev())).toEqual({
-			physdev: true,
-			cellInfo: 'rich',
-			esimStatus: true,
-			opSerialization: true,
-		});
-	});
-});
-
-describe('detectMmFeatures — property presence overrides the version', () => {
-	test('physdev is property-driven: 1.24 version but no Physdev property ⇒ false', () => {
-		expect(detectMmFeatures('1.24.0', probe()).physdev).toBe(false);
-	});
-
-	test('a 1.22+ modem that omits Physdev still reports rich cell info by version', () => {
-		expect(detectMmFeatures('1.22.0', probe()).cellInfo).toBe('rich');
-	});
-
-	test('rich cell-info fields promote the tier even without a version signal', () => {
-		const withFields = probe({ cellInfoFields: new Set(['serving-type', 'bandwidth']) });
-		expect(detectMmFeatures('1.20.0', withFields).cellInfo).toBe('rich');
-	});
-});
-
-describe('detectMmFeatures — degrade paths', () => {
-	test('below 1.20 has no cell info, no eSIM, no serialization', () => {
-		expect(detectMmFeatures('1.18.0', probe({ properties: new Set(['Device']) }))).toEqual({
-			physdev: false,
-			cellInfo: 'none',
-			esimStatus: false,
-			opSerialization: false,
-		});
-	});
-
-	test('a modem advertising no cell-info capability degrades to none on a supported version', () => {
-		expect(detectMmFeatures('1.24.0', withPhysdevNoCellInfo()).cellInfo).toBe('none');
-	});
-
-	test('an eSIM property forces esimStatus true even on an unparseable version', () => {
-		const esimProbe = probe({ properties: new Set(['EsimStatus']) });
-		expect(detectMmFeatures('garbage', esimProbe).esimStatus).toBe(true);
-	});
-});
-
-describe('detectMmFeatures — unknown future version probes, never throws', () => {
-	test('1.26.0 falls back to property probing, not a whitelist throw', () => {
-		expect(() => detectMmFeatures('1.26.0', withPhysdev())).not.toThrow();
-		expect(detectMmFeatures('1.26.0', withPhysdev())).toEqual({
-			physdev: true,
-			cellInfo: 'rich',
-			esimStatus: true,
-			opSerialization: true,
-		});
-	});
-
-	test('a totally unparseable version degrades to the safe floor (property-only physdev)', () => {
-		const physdevOnly = { properties: new Set(['Device', 'Physdev']) };
-		expect(detectMmFeatures('???', physdevOnly)).toEqual({
-			physdev: true,
-			cellInfo: 'none',
-			esimStatus: false,
-			opSerialization: false,
-		});
-	});
-});
-
-function withPhysdevNoCellInfo(): MmPropertyProbe {
-	return { properties: new Set([...BASE_MODEM_PROPS, 'Physdev']), cellInfoAvailable: false };
-}
-
-describe('probeModemProperties', () => {
-	test('collects property names across Modem, Modem3gpp and the active SIM', () => {
-		const tree: DecodedManagedObjects = [
-			[
-				'/org/freedesktop/ModemManager1/Modem/0',
-				[
-					[
-						'org.freedesktop.ModemManager1.Modem',
-						[
-							['Device', { signature: 's', value: 'slot-usb2-1' }],
-							['Physdev', { signature: 's', value: '/sys/devices/usb2' }],
-							['Sim', { signature: 'o', value: '/org/freedesktop/ModemManager1/SIM/0' }],
-						],
-					],
-					[
-						'org.freedesktop.ModemManager1.Modem.Modem3gpp',
-						[['Imei', { signature: 's', value: '490154203237518' }]],
-					],
-				],
-			],
-			[
-				'/org/freedesktop/ModemManager1/SIM/0',
-				[['org.freedesktop.ModemManager1.Sim', [['SimType', { signature: 'u', value: 2 }]]]],
-			],
-		];
-		const result = probeModemProperties(tree, '/org/freedesktop/ModemManager1/Modem/0');
-		expect(result.properties.has('Physdev')).toBe(true);
-		expect(result.properties.has('Imei')).toBe(true);
-		expect(result.properties.has('SimType')).toBe(true);
-	});
-});

package/src/backend/features.ts

@@ -1,179 +0,0 @@
-// ModemManager feature detection — what a given MM daemon can actually do.
-//
-// A3.2 must run against MM 1.20 (the bookworm floor), 1.22, 1.24, and versions
-// nobody has shipped yet. The plan is explicit that this is NOT a version-string
-// whitelist: a version we have never seen must degrade gracefully by PROBING the
-// observed property set, never throw. So detection combines two signals:
-//
-//   - the daemon `Version` string (a floor: e.g. eSIM read model is 1.20+), and
-//   - the properties actually present on the observed modem (authoritative for
-//     `physdev` — the plan requires `physdev` be true ONLY when the `Physdev`
-//     property is really there, never merely inferred from a version number).
-//
-// Property facts pinned by the reviewed design (draft §Oracle round-2 #9 / round-4):
-//   - `Modem.Device`  carries the udev slot UID on ALL versions.
-//   - `Modem.Physdev` is the physical topology path, 1.22+ ONLY.
-//   - there is NO `PhysdevUid` property anywhere — do not look for one.
-
-import { MODEM_IFACE, MODEM3GPP_IFACE, SIM_IFACE } from './constants';
-import { type DecodedManagedObjects, findInterface, followObjectPath } from './managed-objects';
-
-/** The capabilities the D-Bus backend gates its behaviour on. */
-export interface MmFeatures {
-	/** `Modem.Physdev` present (physical topology path, 1.22+). Property-probed. */
-	readonly physdev: boolean;
-	/**
-	 * Cell-info tier:
-	 *   - `none`  — below 1.20, or the modem advertises no cell-info capability.
-	 *   - `basic` — 1.20/1.21 `GetCellInfo`.
-	 *   - `rich`  — 1.22+ (serving-type / bandwidth fields).
-	 */
-	readonly cellInfo: 'none' | 'basic' | 'rich';
-	/** eSIM read model (`Sim.SimType` / `Sim.EsimStatus`), 1.20+. */
-	readonly esimStatus: boolean;
-	/** Per-modem operation serialization is available (the shared disruptive actor). */
-	readonly opSerialization: boolean;
-}
-
-/**
- * What A3.2 observed about ONE modem's property surface.
- *
- * `properties` is the union of property NAMES seen across the modem's interfaces
- * (built by `probeModemProperties` from a decoded `GetManagedObjects` tree). The
- * two optional fields let a caller feed richer cell-info evidence than the static
- * object tree carries — MM does not advertise cell-info richness as a Modem
- * property (it comes back from the `GetCellInfo` method), so a backend that has
- * probed cell info can pass what it saw; absent that, detection falls back to the
- * version + `Physdev` co-introduction signal.
- */
-export interface MmPropertyProbe {
-	/** Property names present on the observed modem (Modem + Modem3gpp + active SIM). */
-	readonly properties: ReadonlySet<string>;
-	/** Explicit "modem advertises cell info": `false` forces `cellInfo: 'none'`. */
-	readonly cellInfoAvailable?: boolean;
-	/** Cell-info field names seen in a probe; `serving-type`/`bandwidth` ⇒ `rich`. */
-	readonly cellInfoFields?: ReadonlySet<string>;
-}
-
-/** A parsed `major.minor` MM version. `null` when the string is not parseable. */
-export interface MmVersion {
-	readonly major: number;
-	readonly minor: number;
-}
-
-const VERSION_PATTERN = /^(\d+)\.(\d+)(?:\.\d+)*/;
-
-/**
- * Parse an MM `Version` string (`1.20.0`, `1.24`, `1.26.0-rc1`, …) to `major.minor`.
- * Returns `null` on anything unparseable — callers must degrade, never throw.
- */
-export function parseMmVersion(version: string): MmVersion | null {
-	const match = VERSION_PATTERN.exec(version.trim());
-	if (match === null) {
-		return null;
-	}
-	const major = Number(match[1]);
-	const minor = Number(match[2]);
-	if (!Number.isSafeInteger(major) || !Number.isSafeInteger(minor)) {
-		return null;
-	}
-	return { major, minor };
-}
-
-/** Whether `version` is at least `major.minor` (false when unparseable). */
-function atLeast(version: MmVersion | null, major: number, minor: number): boolean {
-	if (version === null) {
-		return false;
-	}
-	return version.major > major || (version.major === major && version.minor >= minor);
-}
-
-/** MM baseline this stack supports — eSIM read model, `GetCellInfo`, Signal.Setup. */
-const MM_MIN = { major: 1, minor: 20 } as const;
-/** Physdev + rich cell-info were co-introduced at 1.22. */
-const MM_RICH = { major: 1, minor: 22 } as const;
-
-function detectCellInfo(
-	probe: MmPropertyProbe,
-	supported: boolean,
-	modern: boolean,
-	physdev: boolean,
-): MmFeatures['cellInfo'] {
-	// Version floor first: below 1.20 there is no GetCellInfo at all.
-	if (!supported) {
-		return 'none';
-	}
-	// A modem that explicitly advertises no cell-info capability degrades to none,
-	// even on a version that would otherwise support it.
-	if (probe.cellInfoAvailable === false) {
-		return 'none';
-	}
-	const fields = probe.cellInfoFields;
-	if (fields !== undefined && (fields.has('serving-type') || fields.has('bandwidth'))) {
-		return 'rich';
-	}
-	// 1.22 co-introduced `Physdev` and the rich cell-info fields, so either signal
-	// promotes the tier — this is what makes an unseen future version (e.g. 1.26)
-	// resolve to `rich` by probing rather than by matching a whitelist.
-	if (modern || physdev) {
-		return 'rich';
-	}
-	return 'basic';
-}
-
-/**
- * Detect what an MM daemon can do from its version string AND the properties
- * observed on a modem. Pure — no I/O, never throws (an unparseable version yields
- * the safe floor: property-probed `physdev`, everything else off).
- */
-export function detectMmFeatures(version: string, probe: MmPropertyProbe): MmFeatures {
-	const parsed = parseMmVersion(version);
-	const supported = atLeast(parsed, MM_MIN.major, MM_MIN.minor);
-	const modern = atLeast(parsed, MM_RICH.major, MM_RICH.minor);
-
-	// `physdev` is property-authoritative: present iff the `Physdev` property is
-	// really in the observed set (never inferred from the version alone).
-	const physdev = probe.properties.has('Physdev');
-
-	const esimStatus =
-		probe.properties.has('SimType') || probe.properties.has('EsimStatus') || supported;
-
-	const cellInfo = detectCellInfo(probe, supported, modern, physdev);
-
-	return { physdev, cellInfo, esimStatus, opSerialization: supported };
-}
-
-/**
- * Build an `MmPropertyProbe` for one modem from a decoded `GetManagedObjects` tree:
- * the union of property names on its `Modem`, `Modem.Modem3gpp`, and active `Sim`
- * interfaces. Cell-info fields are not carried by the static tree, so the returned
- * probe leaves them unset (detection falls back to version + `Physdev`).
- */
-export function probeModemProperties(
-	tree: DecodedManagedObjects,
-	modemPath: string,
-): MmPropertyProbe {
-	const modem = findInterface(tree, modemPath, MODEM_IFACE);
-	const modem3gpp = findInterface(tree, modemPath, MODEM3GPP_IFACE);
-	const sim = followObjectPath(tree, modem, 'Sim', SIM_IFACE);
-
-	const properties = new Set<string>();
-	for (const source of [modem, modem3gpp, sim]) {
-		if (source === undefined) {
-			continue;
-		}
-		for (const [name] of source) {
-			properties.add(name);
-		}
-	}
-	return { properties };
-}
-
-/** Convenience: detect features straight off a decoded tree for one modem. */
-export function detectModemFeatures(
-	version: string,
-	tree: DecodedManagedObjects,
-	modemPath: string,
-): MmFeatures {
-	return detectMmFeatures(version, probeModemProperties(tree, modemPath));
-}

package/src/backend/identity-ladder.test.ts

@@ -1,117 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import {
-	canBindPolicy,
-	imeiEquipmentId,
-	logicalSlotId,
-	NO_EQUIPMENT_ID,
-	PolicyBindingRefusedError,
-	policyBindingKey,
-} from '../domain';
-import {
-	looksLikeSlotUid,
-	type ModemIdentityFacts,
-	resolveModemIdentities,
-	resolveModemIdentity,
-} from './identity-ladder';
-
-const IMEI_A = '490154203237518';
-const IMEI_B = '356938035643809';
-const PATH = '/org/freedesktop/ModemManager1/Modem/0';
-
-function facts(overrides: Partial<ModemIdentityFacts> = {}): ModemIdentityFacts {
-	return { runtimePath: PATH, equipmentId: imeiEquipmentId(IMEI_A), ...overrides };
-}
-
-describe('looksLikeSlotUid', () => {
-	test('our slot-* naming is detected', () => {
-		expect(looksLikeSlotUid('slot-usb2-1')).toBe(true);
-	});
-
-	test('MM path-shaped default is not a slot UID', () => {
-		expect(looksLikeSlotUid('/sys/devices/pci0000:00/usb2')).toBe(false);
-	});
-
-	test('the bare prefix alone is not a slot UID', () => {
-		expect(looksLikeSlotUid('slot-')).toBe(false);
-	});
-
-	test('an absent Device is not a slot UID', () => {
-		expect(looksLikeSlotUid(undefined)).toBe(false);
-	});
-});
-
-describe('identity ladder rungs (in priority order)', () => {
-	test('rung 1: a slot-UID Device wins over Physdev and ports', () => {
-		const resolved = resolveModemIdentity(
-			facts({ device: 'slot-usb2-1', physdev: '/sys/devices/usb2', ports: ['ttyUSB0'] }),
-		);
-		expect(resolved.slotSource).toBe('device-slot-uid');
-		expect(resolved.confidence).toBe('high');
-		expect(resolved.identity.logicalSlotId).toBe(logicalSlotId('slot-usb2-1'));
-		expect(resolved.stableKey).toBe('slot:slot-usb2-1');
-	});
-
-	test('rung 2: Physdev is used when Device is a path-shaped default', () => {
-		const resolved = resolveModemIdentity(
-			facts({ device: '/sys/devices/usb2', physdev: '/sys/devices/pci/usb2/2-1' }),
-		);
-		expect(resolved.slotSource).toBe('physdev');
-		expect(resolved.confidence).toBe('high');
-		expect(resolved.stableKey).toBe('physdev:/sys/devices/pci/usb2/2-1');
-	});
-
-	test('rung 3: a ports-derived sysfs walk when no slot UID or Physdev', () => {
-		const resolved = resolveModemIdentity(facts({ ports: ['wwan0', 'ttyUSB2', 'ttyUSB0'] }));
-		expect(resolved.slotSource).toBe('sysfs-walk');
-		expect(resolved.confidence).toBe('medium');
-		expect(resolved.stableKey).toBe('sysfs:ttyUSB0+ttyUSB2+wwan0');
-	});
-
-	test('rung 4: equipment fallback is low confidence with no slot', () => {
-		const resolved = resolveModemIdentity(facts());
-		expect(resolved.slotSource).toBe('equipment-fallback');
-		expect(resolved.confidence).toBe('low');
-		expect(resolved.identity.logicalSlotId).toBeUndefined();
-		expect(resolved.stableKey).toBe(`equip:${IMEI_A}`);
-	});
-
-	test('rung 4 with no equipment id keys off the transient path', () => {
-		const resolved = resolveModemIdentity(facts({ equipmentId: NO_EQUIPMENT_ID }));
-		expect(resolved.stableKey).toBe(`path:${PATH}`);
-	});
-});
-
-describe('durable policy binding through the ladder', () => {
-	test('a slot-resolved unique modem may bind durable policy', () => {
-		const resolved = resolveModemIdentity(facts({ device: 'slot-usb2-1' }));
-		expect(canBindPolicy(resolved.identity)).toBe(true);
-		expect(policyBindingKey(resolved.identity).logicalSlotId).toBe(logicalSlotId('slot-usb2-1'));
-	});
-
-	test('duplicate-IMEI fixture: the ladder falls to low-confidence equipment fallback and refuses binding', () => {
-		const resolved = resolveModemIdentities([
-			facts({
-				runtimePath: '/org/freedesktop/ModemManager1/Modem/0',
-				equipmentId: imeiEquipmentId(IMEI_A),
-			}),
-			facts({
-				runtimePath: '/org/freedesktop/ModemManager1/Modem/1',
-				equipmentId: imeiEquipmentId(IMEI_A),
-			}),
-		]);
-		for (const each of resolved) {
-			expect(each.slotSource).toBe('equipment-fallback');
-			expect(each.identity.equipmentId.confidence).toBe('low');
-			expect(canBindPolicy(each.identity)).toBe(false);
-			expect(() => policyBindingKey(each.identity)).toThrow(PolicyBindingRefusedError);
-		}
-	});
-
-	test('unique IMEIs are NOT demoted in a batch resolve', () => {
-		const resolved = resolveModemIdentities([
-			facts({ device: 'slot-a', equipmentId: imeiEquipmentId(IMEI_A) }),
-			facts({ device: 'slot-b', equipmentId: imeiEquipmentId(IMEI_B) }),
-		]);
-		expect(resolved.every((each) => each.identity.equipmentId.confidence === 'high')).toBe(true);
-	});
-});

package/src/backend/identity-ladder.ts

@@ -1,221 +0,0 @@
-// The identity ladder — resolving a STABLE slot handle for a live modem.
-//
-// A modem's D-Bus object path (`/org/freedesktop/ModemManager1/Modem/3`) is a
-// per-boot, per-plug value: it changes on replug and daemon restart, so it can
-// never be the durable key. The ladder derives a stable key by trying, in order:
-//
-//   1. slot-UID in `Modem.Device` — when OUR udev rules label the slot they set
-//      `Device` to a `slot-*` UID (e.g. `slot-usb2-1`). That is stable and ours,
-//      distinguishable from MM's own path-shaped default (`/sys/devices/...`).
-//   2. `Modem.Physdev` (1.22+) — the physical USB topology path. Stable across
-//      replug into the same port; used when no slot-UID is present.
-//   3. a ports-derived sysfs walk — a deterministic key from the modem's port
-//      list when neither of the above is available (MM 1.20, no udev rule yet).
-//   4. equipment-id fallback — LOW confidence. Per A2.1's ambiguity rules a
-//      low-confidence identity must never bind durable policy, so this rung sets
-//      `confidence: 'low'` and `canBindPolicy` refuses on an ambiguous equipment id.
-//
-// Phase A note: no image-pipeline udev rules ship yet, so on the bench `Device`
-// is usually MM's path-shaped default and the ladder lands on Physdev / sysfs.
-// The `slot-*` heuristic is documented here so a bench operator can label a slot
-// by hand and see rung 1 fire.
-
-import {
-	demoteToLowConfidence,
-	type EquipmentId,
-	type IdentityConfidence,
-	imeiEquipmentId,
-	type LogicalSlotId,
-	logicalSlotId,
-	type ModemIdentity,
-	runtimePath,
-} from '../domain';
-import { MODEM_IFACE, MODEM3GPP_IFACE } from './constants';
-import {
-	type DecodedManagedObjects,
-	findInterface,
-	propValue,
-	stringProp,
-} from './managed-objects';
-
-/** Which rung of the ladder produced the stable key. */
-export type SlotSource = 'device-slot-uid' | 'physdev' | 'sysfs-walk' | 'equipment-fallback';
-
-/** The prefix OUR udev rules use to label a slot in `Modem.Device`. */
-export const SLOT_UID_PREFIX = 'slot-';
-
-/** The raw facts the ladder resolves from — one modem's observed identity inputs. */
-export interface ModemIdentityFacts {
-	/** The live MM object path (becomes `runtimePath`; never a durable key). */
-	readonly runtimePath: string;
-	/** `Modem.Device` — a `slot-*` UID (ours) or MM's path-shaped default. */
-	readonly device?: string;
-	/** `Modem.Physdev` — physical topology path (1.22+; absent on 1.20). */
-	readonly physdev?: string;
-	/** The modem's port device names (e.g. `ttyUSB0`, `wwan0`) for the sysfs walk. */
-	readonly ports?: readonly string[];
-	/** IMEI/serial equipment id with its own confidence (A2.1). */
-	readonly equipmentId: EquipmentId;
-}
-
-/** The ladder's output: a resolved identity plus how (and how firmly) we got it. */
-export interface ResolvedIdentity {
-	/** The four-part identity; `logicalSlotId` is set for rungs 1-3 only. */
-	readonly identity: ModemIdentity;
-	/** Which rung produced the result. */
-	readonly slotSource: SlotSource;
-	/** Confidence in the SLOT resolution (rung 4 is always `low`). */
-	readonly confidence: IdentityConfidence;
-	/** The durable row key — stable across replug for rungs 1-3 (and unique-IMEI rung 4). */
-	readonly stableKey: string;
-}
-
-/**
- * Whether a `Modem.Device` value is one of OUR slot UIDs (shaped `slot-*`) rather
- * than MM's path-shaped default. This is the documented Phase-A heuristic that
- * keeps a hand-labelled slot preferred over a `/sys/devices/...` path.
- */
-export function looksLikeSlotUid(device: string | undefined): boolean {
-	if (device === undefined) {
-		return false;
-	}
-	return device.startsWith(SLOT_UID_PREFIX) && device.length > SLOT_UID_PREFIX.length;
-}
-
-/** Derive a deterministic key from a modem's port list (sorted, stable across replug). */
-function sysfsWalkKey(ports: readonly string[]): string | undefined {
-	const named = ports.map((p) => p.trim()).filter((p) => p.length > 0);
-	if (named.length === 0) {
-		return undefined;
-	}
-	return [...named].sort().join('+');
-}
-
-function buildIdentity(facts: ModemIdentityFacts, slot: LogicalSlotId | undefined): ModemIdentity {
-	return {
-		equipmentId: facts.equipmentId,
-		runtimePath: runtimePath(facts.runtimePath),
-		...(slot !== undefined ? { logicalSlotId: slot } : {}),
-	};
-}
-
-/**
- * Resolve ONE modem's stable identity by walking the ladder. Pure — no I/O.
- *
- * Rungs 1-3 yield a `logicalSlotId` and a stable key that survives replug into the
- * same slot. Rung 4 (equipment fallback) yields NO slot and `confidence: 'low'`,
- * so a durable policy bound via `policyBindingKey` is refused for an ambiguous
- * (duplicate/zero) equipment id.
- */
-export function resolveModemIdentity(facts: ModemIdentityFacts): ResolvedIdentity {
-	// Rung 1 — our slot-UID in `Device`.
-	if (looksLikeSlotUid(facts.device)) {
-		const device = facts.device as string;
-		const slot = logicalSlotId(device);
-		return {
-			identity: buildIdentity(facts, slot),
-			slotSource: 'device-slot-uid',
-			confidence: 'high',
-			stableKey: `slot:${device}`,
-		};
-	}
-
-	// Rung 2 — `Physdev` physical topology path (1.22+).
-	const physdev = facts.physdev?.trim();
-	if (physdev !== undefined && physdev.length > 0) {
-		const slot = logicalSlotId(`physdev:${physdev}`);
-		return {
-			identity: buildIdentity(facts, slot),
-			slotSource: 'physdev',
-			confidence: 'high',
-			stableKey: `physdev:${physdev}`,
-		};
-	}
-
-	// Rung 3 — ports-derived sysfs walk.
-	const walk = facts.ports !== undefined ? sysfsWalkKey(facts.ports) : undefined;
-	if (walk !== undefined) {
-		const slot = logicalSlotId(`sysfs:${walk}`);
-		return {
-			identity: buildIdentity(facts, slot),
-			slotSource: 'sysfs-walk',
-			confidence: 'medium',
-			stableKey: `sysfs:${walk}`,
-		};
-	}
-
-	// Rung 4 — equipment fallback, LOW confidence, no durable slot.
-	const equip = facts.equipmentId;
-	const stableKey =
-		equip.provenance !== 'none' && equip.value.trim().length > 0
-			? `equip:${equip.value}`
-			: `path:${facts.runtimePath}`;
-	return {
-		identity: buildIdentity(facts, undefined),
-		slotSource: 'equipment-fallback',
-		confidence: 'low',
-		stableKey,
-	};
-}
-
-/**
- * Resolve a batch of modems, demoting any equipment id that appears on more than
- * one modem to LOW confidence FIRST (cross-modem duplicate detection A2.1 cannot do
- * from a single value). A duplicate IMEI thus reaches rung 4 with a low-confidence
- * equipment id, and `canBindPolicy` refuses durable binding on it.
- */
-export function resolveModemIdentities(
-	factsList: readonly ModemIdentityFacts[],
-): ResolvedIdentity[] {
-	const counts = new Map<string, number>();
-	for (const facts of factsList) {
-		const { equipmentId } = facts;
-		if (equipmentId.provenance !== 'none' && equipmentId.value.trim().length > 0) {
-			counts.set(equipmentId.value, (counts.get(equipmentId.value) ?? 0) + 1);
-		}
-	}
-	return factsList.map((facts) => {
-		const { equipmentId } = facts;
-		const duplicated =
-			equipmentId.provenance !== 'none' && (counts.get(equipmentId.value) ?? 0) > 1;
-		const resolvedFacts: ModemIdentityFacts = duplicated
-			? { ...facts, equipmentId: demoteToLowConfidence(equipmentId) }
-			: facts;
-		return resolveModemIdentity(resolvedFacts);
-	});
-}
-
-/** MM `Modem.Ports` is `a(su)`: entries of `[portName, portType]`. */
-function portNames(value: ReturnType<typeof propValue>): string[] | undefined {
-	if (!Array.isArray(value)) {
-		return undefined;
-	}
-	const names = value
-		.map((entry) => (Array.isArray(entry) ? entry[0] : undefined))
-		.filter((name): name is string => typeof name === 'string');
-	return names.length > 0 ? names : undefined;
-}
-
-/**
- * Extract one modem's `ModemIdentityFacts` from a decoded `GetManagedObjects` tree —
- * the bridge real backends use to feed the ladder from an observed snapshot.
- */
-export function modemIdentityFactsFromTree(
-	tree: DecodedManagedObjects,
-	modemPath: string,
-): ModemIdentityFacts {
-	const modem = findInterface(tree, modemPath, MODEM_IFACE);
-	const modem3gpp = findInterface(tree, modemPath, MODEM3GPP_IFACE);
-	const equipment = stringProp(modem, 'EquipmentIdentifier') ?? stringProp(modem3gpp, 'Imei') ?? '';
-	const device = stringProp(modem, 'Device');
-	const physdev = stringProp(modem, 'Physdev');
-	const ports = portNames(propValue(modem, 'Ports'));
-
-	return {
-		runtimePath: modemPath,
-		equipmentId: imeiEquipmentId(equipment),
-		...(device !== undefined ? { device } : {}),
-		...(physdev !== undefined ? { physdev } : {}),
-		...(ports !== undefined ? { ports } : {}),
-	};
-}