@ceralive/modem-control 1.0.0 → 1.2.0

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

@@ -1,89 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { imeiEquipmentId, logicalSlotId, runtimePath } from '../domain';
-import { type ModemIdentityFacts, resolveModemIdentity } from './identity-ladder';
-import { IdentityRegistry } from './identity-registry';
-
-const IMEI_A = '490154203237518';
-const IMEI_B = '356938035643809';
-
-function resolvedAt(
-	device: string,
-	imei: string,
-	path: string,
-	extra: Partial<ModemIdentityFacts> = {},
-) {
-	return resolveModemIdentity({
-		runtimePath: path,
-		device,
-		equipmentId: imeiEquipmentId(imei),
-		...extra,
-	});
-}
-
-describe('IdentityRegistry transitions', () => {
-	test('a fresh stable key attaches a new row', () => {
-		const registry = new IdentityRegistry();
-		const transition = registry.apply(resolvedAt('slot-a', IMEI_A, '/Modem/0'));
-		expect(transition.kind).toBe('attached');
-		expect(registry.rows).toHaveLength(1);
-	});
-
-	test('replug into the SAME slot keeps ONE row and updates the path', () => {
-		const registry = new IdentityRegistry();
-		registry.apply(resolvedAt('slot-a', IMEI_A, '/Modem/0'));
-		const transition = registry.apply(resolvedAt('slot-a', IMEI_A, '/Modem/7'));
-
-		expect(transition.kind).toBe('replugged');
-		expect(registry.rows).toHaveLength(1);
-		expect(registry.rows[0]?.runtimePath).toBe(runtimePath('/Modem/7'));
-		if (transition.kind === 'replugged') {
-			expect(transition.previousPath).toBe(runtimePath('/Modem/0'));
-		}
-	});
-
-	test('a different modem in the SAME slot is an equipment-swap (slot inherits policy)', () => {
-		const registry = new IdentityRegistry();
-		registry.apply(resolvedAt('slot-a', IMEI_A, '/Modem/0'));
-		const transition = registry.apply(resolvedAt('slot-a', IMEI_B, '/Modem/1'));
-
-		expect(transition.kind).toBe('equipment-swapped-in-slot');
-		expect(registry.rows).toHaveLength(1);
-		expect(registry.rows[0]?.logicalSlotId).toBe(logicalSlotId('slot-a'));
-		expect(
-			registry.rows[0]?.equipmentId.provenance === 'imei' && registry.rows[0]?.equipmentId.value,
-		).toBe(IMEI_B);
-		if (transition.kind === 'equipment-swapped-in-slot') {
-			expect(
-				transition.previousEquipment.provenance === 'imei' && transition.previousEquipment.value,
-			).toBe(IMEI_A);
-		}
-	});
-
-	test('the SAME equipment in a different slot is an equipment-move', () => {
-		const registry = new IdentityRegistry();
-		registry.apply(resolvedAt('slot-a', IMEI_A, '/Modem/0'));
-		const transition = registry.apply(resolvedAt('slot-b', IMEI_A, '/Modem/2'));
-
-		expect(transition.kind).toBe('equipment-moved');
-		expect(registry.rows).toHaveLength(1);
-		expect(registry.rows[0]?.logicalSlotId).toBe(logicalSlotId('slot-b'));
-		if (transition.kind === 'equipment-moved') {
-			expect(transition.previousKey).toBe('slot:slot-a');
-			expect(transition.previousSlot).toBe(logicalSlotId('slot-a'));
-		}
-	});
-
-	test('two distinct slots keep two independent rows', () => {
-		const registry = new IdentityRegistry();
-		registry.apply(resolvedAt('slot-a', IMEI_A, '/Modem/0'));
-		registry.apply(resolvedAt('slot-b', IMEI_B, '/Modem/1'));
-		expect(registry.rows).toHaveLength(2);
-	});
-
-	test('remove drops a row by stable key', () => {
-		const registry = new IdentityRegistry();
-		registry.apply(resolvedAt('slot-a', IMEI_A, '/Modem/0'));
-		registry.remove('slot:slot-a');
-		expect(registry.rows).toHaveLength(0);
-	});
-});

package/src/backend/identity-registry.ts

@@ -1,151 +0,0 @@
-// The identity registry — ONE logical row per physical slot, across replugs.
-//
-// The epoch observer (A3.1) keys rows by the MM object path, which CHANGES on
-// replug and daemon restart. This registry sits above it and keys rows by the
-// STABLE identifier the ladder resolves (slot-UID / Physdev / sysfs / unique
-// equipment id), so a modem that disconnects and reconnects to the SAME slot
-// resolves to the SAME logical row instead of a duplicate.
-//
-// It also names the transitions the ladder can observe:
-//
-//   - `attached`                  — a stable key we have not seen before.
-//   - `replugged`                 — same stable key, same equipment: one row, new path.
-//   - `equipment-swapped-in-slot` — same slot, DIFFERENT equipment. The slot keeps
-//                                   its policy (slot-inherits-policy): unplug modem A,
-//                                   plug modem B into the same slot, B adopts A's
-//                                   slot-bound policy.
-//   - `equipment-moved`           — same equipment, DIFFERENT slot: the modem was
-//                                   physically moved to another port.
-
-import type { EquipmentId, LogicalSlotId, RuntimePath } from '../domain';
-import type { ResolvedIdentity } from './identity-ladder';
-
-/** One durable logical row, keyed by the ladder's stable identifier. */
-export interface IdentityRow {
-	/** The stable durable key (`slot:…` / `physdev:…` / `sysfs:…` / `equip:…`). */
-	readonly stableKey: string;
-	/** The resolved slot, when the row was slot-resolved (rungs 1-3). */
-	readonly logicalSlotId?: LogicalSlotId;
-	/** The equipment currently occupying this slot. */
-	readonly equipmentId: EquipmentId;
-	/** The live MM path — updated on every replug (never a durable key). */
-	readonly runtimePath: RuntimePath;
-}
-
-/** A transition the registry detected while applying a resolved identity. */
-export type IdentityTransition =
-	| { readonly kind: 'attached'; readonly row: IdentityRow }
-	| { readonly kind: 'replugged'; readonly row: IdentityRow; readonly previousPath: RuntimePath }
-	| {
-			readonly kind: 'equipment-swapped-in-slot';
-			readonly row: IdentityRow;
-			readonly previousEquipment: EquipmentId;
-	  }
-	| {
-			readonly kind: 'equipment-moved';
-			readonly row: IdentityRow;
-			readonly previousKey: string;
-			readonly previousSlot?: LogicalSlotId;
-	  };
-
-const equipmentValue = (equipment: EquipmentId): string | undefined =>
-	equipment.provenance !== 'none' && equipment.value.trim().length > 0
-		? equipment.value
-		: undefined;
-
-/**
- * Tracks logical modem rows across replug/swap/move. Stateful by design — it holds
- * the last-known row per stable key. `apply()` folds one resolved identity in and
- * reports the transition it produced.
- */
-export class IdentityRegistry {
-	readonly #rows = new Map<string, IdentityRow>();
-
-	/** A snapshot of the current logical rows, in insertion order. */
-	get rows(): IdentityRow[] {
-		return [...this.#rows.values()];
-	}
-
-	/** The row for a stable key, or `undefined`. */
-	get(stableKey: string): IdentityRow | undefined {
-		return this.#rows.get(stableKey);
-	}
-
-	/** Drop a row (e.g. after a current-epoch removal). */
-	remove(stableKey: string): void {
-		this.#rows.delete(stableKey);
-	}
-
-	/**
-	 * Fold one resolved identity into the registry and report the transition.
-	 * Keeps ONE row per stable key: a replug into the same slot updates the live
-	 * path in place rather than adding a duplicate.
-	 */
-	apply(resolved: ResolvedIdentity): IdentityTransition {
-		const row = this.#rowFrom(resolved);
-		const existing = this.#rows.get(row.stableKey);
-
-		if (existing !== undefined) {
-			return this.#applyToExisting(existing, resolved, row);
-		}
-
-		// A unique equipment id at a NEW stable key that already lives elsewhere
-		// means the modem physically moved to a different slot/port.
-		const moved = this.#findByEquipment(row.equipmentId, row.stableKey);
-		if (moved !== undefined) {
-			this.#rows.delete(moved.stableKey);
-			this.#rows.set(row.stableKey, row);
-			return {
-				kind: 'equipment-moved',
-				row,
-				previousKey: moved.stableKey,
-				...(moved.logicalSlotId !== undefined ? { previousSlot: moved.logicalSlotId } : {}),
-			};
-		}
-
-		this.#rows.set(row.stableKey, row);
-		return { kind: 'attached', row };
-	}
-
-	#applyToExisting(
-		existing: IdentityRow,
-		resolved: ResolvedIdentity,
-		row: IdentityRow,
-	): IdentityTransition {
-		const before = equipmentValue(existing.equipmentId);
-		const after = equipmentValue(resolved.identity.equipmentId);
-
-		if (before !== undefined && after !== undefined && before !== after) {
-			// Same slot, different equipment — the slot keeps its policy binding.
-			this.#rows.set(row.stableKey, row);
-			return { kind: 'equipment-swapped-in-slot', row, previousEquipment: existing.equipmentId };
-		}
-
-		// Same slot, same (or unchanged) equipment — a replug: one row, new path.
-		this.#rows.set(row.stableKey, row);
-		return { kind: 'replugged', row, previousPath: existing.runtimePath };
-	}
-
-	#rowFrom(resolved: ResolvedIdentity): IdentityRow {
-		const { identity, stableKey } = resolved;
-		return {
-			stableKey,
-			equipmentId: identity.equipmentId,
-			runtimePath: identity.runtimePath,
-			...(identity.logicalSlotId !== undefined ? { logicalSlotId: identity.logicalSlotId } : {}),
-		};
-	}
-
-	#findByEquipment(equipment: EquipmentId, exceptKey: string): IdentityRow | undefined {
-		const value = equipmentValue(equipment);
-		if (value === undefined) {
-			return undefined;
-		}
-		for (const row of this.#rows.values()) {
-			if (row.stableKey !== exceptKey && equipmentValue(row.equipmentId) === value) {
-				return row;
-			}
-		}
-		return undefined;
-	}
-}

package/src/backend/index.ts

@@ -1,236 +0,0 @@
-// Backend adapters — the concrete D-Bus implementations of the port contracts.
-//
-// A3.1 lands the epoch-scoped `MmDbusObserver` (the read side). A3.2 adds MM
-// feature detection + the stable identity ladder. Later A3 waves add mutations +
-// Signal.Setup (A3.3) and the recovery ladder (A3.4) here.
-
-export {
-	AT_BASELINE_ALLOWLIST,
-	type AtAuditEntry,
-	type AtAuditSink,
-	AtCommandLease,
-	type AtCommandLeaseDeps,
-	AtCommandNotAllowedError,
-	type AtCommandSender,
-	AtCommandTimeoutError,
-	type AtResponse,
-	computeAtAllowlist,
-} from './at-lease';
-export {
-	type CellInfoProvenance,
-	type CellReading,
-	compareServing,
-	normalizeCellInfo,
-	normalizeCellReading,
-	selectServingCell,
-} from './cell-info';
-export {
-	MM_BUS_NAME,
-	MM_MANAGER_IFACE,
-	MM_ROOT_PATH,
-	MODEM_IFACE,
-	MODEM3GPP_IFACE,
-	SIM_IFACE,
-} from './constants';
-export {
-	classifyDevice,
-	type DeviceClass,
-	type DeviceClassification,
-	descriptorsMatch,
-	detectUsbMode,
-	type UsbDeviceSnapshot,
-	type UsbInterface,
-} from './device-classifier';
-export {
-	buildEnrichment,
-	type EsimInfo,
-	type EsimStatus,
-	type ModemEnrichment,
-	readEsimInfo,
-	readRevision,
-	type SimType,
-} from './enrichment';
-export {
-	detectMmFeatures,
-	detectModemFeatures,
-	type MmFeatures,
-	type MmPropertyProbe,
-	type MmVersion,
-	parseMmVersion,
-	probeModemProperties,
-} from './features';
-export {
-	looksLikeSlotUid,
-	type ModemIdentityFacts,
-	modemIdentityFactsFromTree,
-	type ResolvedIdentity,
-	resolveModemIdentities,
-	resolveModemIdentity,
-	SLOT_UID_PREFIX,
-	type SlotSource,
-} from './identity-ladder';
-export {
-	IdentityRegistry,
-	type IdentityRow,
-	type IdentityTransition,
-} from './identity-registry';
-export {
-	ALLOW_ALL_INTERLOCK,
-	type InterlockDecision,
-	type InterlockTarget,
-	type LifecycleInterlock,
-} from './lifecycle-interlock';
-export {
-	asManagedObjects,
-	type DecodedInterfaces,
-	type DecodedManagedObjects,
-	type DecodedObject,
-	type DecodedProps,
-	fetchManagedObjects,
-	findInterface,
-	findObject,
-	followObjectPath,
-	hasInterface,
-	numberProp,
-	objectPaths,
-	pathsWithInterface,
-	propValue,
-	stringProp,
-} from './managed-objects';
-export {
-	createMmDbusBackend,
-	MmDbusBackend,
-	type MmDbusBackendOptions,
-} from './mm-backend';
-export { MmMutations, type MmMutationsDeps } from './mm-mutations';
-export {
-	ModemActor,
-	NO_OP_QUIESCE,
-	type QuiesceHook,
-	type QuiesceLeaseHandle,
-	type QuiesceTarget,
-} from './modem-actor';
-export {
-	AUTO_APN_ADVISORY,
-	type AutoApnAdvisory,
-	type AutoApnTransitionResult,
-	autoApnCapableFromVersion,
-	autoApnSupportedByVersion,
-	classifyActivation,
-	type ManualApn,
-	parseNmVersion,
-	probeAutoApnCapability,
-	toAutoArgs,
-	toManualArgs,
-} from './nm-auto-apn';
-export {
-	buildProfile,
-	cliArg,
-	createGsmArgs,
-	flattenPairs,
-	gsmFieldPairs,
-	passwordFlags,
-	patchPairs,
-} from './nm-gsm-fields';
-export {
-	NmcliNmPort,
-	type NmcliNmPortOptions,
-} from './nmcli-nm-port';
-export {
-	type NmcliResult,
-	type NmcliRunner,
-	parseTerse,
-	runNmcli,
-	SpawnNmcliRunner,
-} from './nmcli-runner';
-export {
-	createMmDbusObserver,
-	type EpochRefreshEvent,
-	MmDbusObserver,
-	type MmDbusObserverOptions,
-} from './observer';
-export {
-	NONE_POWER_CAPABILITY,
-	NONE_POWER_HOOK,
-	type PowerCapability,
-	type PowerCapabilityKind,
-	type PowerCycleContext,
-	type PowerCycleResult,
-	type PowerHook,
-	type PreferredUsbMode,
-	unsupportedPowerHook,
-} from './power-contract';
-export {
-	attributeFault,
-	attributeSnapshot,
-	type FaultAttribution,
-	type FaultSymptoms,
-	symptomsFromSnapshot,
-} from './recovery-attribution';
-export {
-	type BudgetDecision,
-	beginAttempt,
-	DEFAULT_RECOVERY_BUDGET,
-	INITIAL_BUDGET_STATE,
-	markRecovered,
-	type RecoveryBudget,
-	type RecoveryBudgetState,
-} from './recovery-budget';
-export {
-	DEFAULT_LADDER_CONFIG,
-	LADDER_ORDER,
-	RecoveryLadder,
-	type RecoveryLadderConfig,
-	type RecoveryLadderDeps,
-	type RecoveryOutcome,
-	type RecoveryOutcomeKind,
-	type RecoveryRequest,
-	type RecoveryRung,
-	type RecoveryStepContext,
-	type RecoveryStepGate,
-	type RecoveryStepReport,
-	type RecoverySteps,
-	type StepOutcome,
-} from './recovery-ladder';
-export { createRouterEthernetProbe, type RouterEthernetProbeDeps } from './router-ethernet';
-export {
-	DEFAULT_SIGNAL_INTERVAL_SECONDS,
-	type SignalCadence,
-	SignalSetupManager,
-	type SignalSetupManagerOptions,
-} from './signal-setup';
-export { sendSimPin, sendSimPuk } from './sim-unlock';
-export {
-	ALLOW_ALL_TRANSITION_INTERLOCK,
-	checkTransitionPreconditions,
-	type InterlockHold,
-	type PreconditionResult,
-	type TransitionInterlock,
-	type TransitionReadiness,
-	type UsbModeTransitionOutcome,
-	type UsbModeTransitionRequest,
-} from './transition-preconditions';
-export {
-	createUhubctlPowerHook,
-	parseUhubctlPortMap,
-	readUhubctlPortMap,
-	SpawnUhubctlRunner,
-	type UhubctlPortMap,
-	type UhubctlPortMapping,
-	type UhubctlPowerHookDeps,
-	type UhubctlResult,
-	type UhubctlRunner,
-	type UsbEnumerationPoller,
-	uhubctlCycleArgv,
-	uhubctlPortMappingSchema,
-	uhubctlPortMapSchema,
-} from './uhubctl-power-hook';
-export * from './usage';
-export {
-	createUsbEnumerator,
-	enumerateUsbDevices,
-	parseUdevDatabase,
-	type UsbEnumerator,
-	type UsbEnumeratorDeps,
-} from './usb-enumerator';
-export { UsbModeTransition, type UsbModeTransitionDeps } from './usb-mode-transition';

package/src/backend/lifecycle-interlock.ts

@@ -1,38 +0,0 @@
-// The pluggable safety interlock the recovery ladder consults before disruption.
-//
-// A disruptive recovery step (deactivate NM, disable MM, Reset(), power-cycle) must
-// never fire while the modem is carrying a live stream. The ladder therefore asks a
-// `LifecycleInterlock` BEFORE every disruptive step. Phase A (CLI) injects the
-// always-allow stub below; Phase B wires CeraUI's real streaming-admission check
-// into this SAME interface — the ladder code does not change, only the injected
-// instance. A4.2's USB-mode transition reuses this exact interlock shape.
-
-/** What a disruptive step is about to act on — enough for an interlock to decide. */
-export interface InterlockTarget {
-	readonly stableKey: string;
-}
-
-/** An interlock verdict. A denial ALWAYS carries a reason (why it is unsafe now). */
-export type InterlockDecision =
-	| { readonly allow: true }
-	| { readonly allow: false; readonly reason: string };
-
-/**
- * The safety interlock consulted before each disruptive recovery step. Returning
- * `{ allow: false, reason }` stops the ladder — the modem is left as-is rather than
- * disrupted mid-stream.
- */
-export interface LifecycleInterlock {
-	canDisrupt(target: InterlockTarget): Promise<InterlockDecision>;
-}
-
-/**
- * The Phase-A interlock: always allows. There is no streaming-admission signal in
- * the CLI, so nothing to block against. Phase B replaces this instance with a
- * real streaming-aware interlock; no ladder code changes.
- */
-export const ALLOW_ALL_INTERLOCK: LifecycleInterlock = {
-	canDisrupt(): Promise<InterlockDecision> {
-		return Promise.resolve({ allow: true });
-	},
-};

package/src/backend/managed-objects.ts

@@ -1,108 +0,0 @@
-// Walkers over a DECODED `GetManagedObjects` / `InterfacesAdded` tree.
-//
-// The transport decodes `a{oa{sa{sv}}}` into nested tuple arrays: a dict `a{sv}`
-// becomes `[key, variant][]` and a variant becomes `{ signature, value }`. These
-// accessors navigate that structure by object path and interface name. They live in
-// `src` (not the A2.3 test fake's `tree.ts`) because the observer that ships must not
-// import test-support — the published package would not contain it.
-
-import type { DbusTransport, DbusValue, DbusVariant } from '../transport';
-import { MM_ROOT_PATH, OBJECT_MANAGER_IFACE } from './constants';
-
-/** One interface's property entries: `[propertyName, variant][]`. */
-export type DecodedProps = ReadonlyArray<readonly [string, DbusVariant]>;
-/** One object's interfaces: `[interfaceName, props][]`. */
-export type DecodedInterfaces = ReadonlyArray<readonly [string, DecodedProps]>;
-/** One managed object: `[objectPath, interfaces]`. */
-export type DecodedObject = readonly [string, DecodedInterfaces];
-/** The whole `a{oa{sa{sv}}}` payload. */
-export type DecodedManagedObjects = readonly DecodedObject[];
-
-/** Treat a `GetManagedObjects` reply body value as the decoded tree. */
-export function asManagedObjects(value: DbusValue | undefined): DecodedManagedObjects {
-	if (!Array.isArray(value)) {
-		throw new TypeError('managed-objects payload is not an array');
-	}
-	return value as unknown as DecodedManagedObjects;
-}
-
-/** Call `ObjectManager.GetManagedObjects` on `destination` and decode the reply. */
-export async function fetchManagedObjects(
-	transport: DbusTransport,
-	destination: string,
-): Promise<DecodedManagedObjects> {
-	const reply = await transport.callMethod({
-		destination,
-		path: MM_ROOT_PATH,
-		interface: OBJECT_MANAGER_IFACE,
-		member: 'GetManagedObjects',
-	});
-	return asManagedObjects(reply.body[0]);
-}
-
-/** Treat an `InterfacesAdded` body (`[path, interfaces]`) as one decoded object. */
-export function asAddedObject(path: DbusValue, interfaces: DbusValue): DecodedObject {
-	if (typeof path !== 'string' || !Array.isArray(interfaces)) {
-		throw new TypeError('InterfacesAdded body is not [objectPath, interfaces]');
-	}
-	return [path, interfaces as unknown as DecodedInterfaces];
-}
-
-/** Every object path in the tree, in wire order. */
-export function objectPaths(tree: DecodedManagedObjects): string[] {
-	return tree.map(([path]) => path);
-}
-
-/** The object at `path`, or `undefined`. */
-export function findObject(tree: DecodedManagedObjects, path: string): DecodedObject | undefined {
-	return tree.find(([objectPath]) => objectPath === path);
-}
-
-/** The property entries of one interface on one object, or `undefined`. */
-export function findInterface(
-	tree: DecodedManagedObjects,
-	path: string,
-	iface: string,
-): DecodedProps | undefined {
-	return findObject(tree, path)?.[1].find(([name]) => name === iface)?.[1];
-}
-
-/** Object paths that carry a given interface. */
-export function pathsWithInterface(tree: DecodedManagedObjects, iface: string): string[] {
-	return tree
-		.filter(([, interfaces]) => interfaces.some(([name]) => name === iface))
-		.map(([path]) => path);
-}
-
-/** Whether an object exposes a given interface. */
-export function hasInterface(tree: DecodedManagedObjects, path: string, iface: string): boolean {
-	return findInterface(tree, path, iface) !== undefined;
-}
-
-/** The inner value of a property (a variant's `.value`), or `undefined`. */
-export function propValue(props: DecodedProps | undefined, name: string): DbusValue | undefined {
-	return props?.find(([key]) => key === name)?.[1]?.value;
-}
-
-/** A string-typed property, or `undefined` if absent / not a string. */
-export function stringProp(props: DecodedProps | undefined, name: string): string | undefined {
-	const value = propValue(props, name);
-	return typeof value === 'string' ? value : undefined;
-}
-
-/** A number-typed property, or `undefined` if absent / not a number. */
-export function numberProp(props: DecodedProps | undefined, name: string): number | undefined {
-	const value = propValue(props, name);
-	return typeof value === 'number' ? value : undefined;
-}
-
-/** Resolve an object-path property (e.g. a modem's `Sim`) to that object's props. */
-export function followObjectPath(
-	tree: DecodedManagedObjects,
-	props: DecodedProps | undefined,
-	propName: string,
-	iface: string,
-): DecodedProps | undefined {
-	const target = propValue(props, propName);
-	return typeof target === 'string' ? findInterface(tree, target, iface) : undefined;
-}