@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/backend/identity-ladder.d.ts

@@ -0,0 +1,57 @@
+import { type EquipmentId, type IdentityConfidence, type ModemIdentity } from '../domain/index.js';
+import { type DecodedManagedObjects } from './managed-objects.js';
+/** 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 declare 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 declare function looksLikeSlotUid(device: string | undefined): boolean;
+/**
+ * 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 declare function resolveModemIdentity(facts: ModemIdentityFacts): ResolvedIdentity;
+/**
+ * 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 declare function resolveModemIdentities(factsList: readonly ModemIdentityFacts[]): ResolvedIdentity[];
+/**
+ * Extract one modem's `ModemIdentityFacts` from a decoded `GetManagedObjects` tree —
+ * the bridge real backends use to feed the ladder from an observed snapshot.
+ */
+export declare function modemIdentityFactsFromTree(tree: DecodedManagedObjects, modemPath: string): ModemIdentityFacts;

package/dist/backend/identity-ladder.js

@@ -0,0 +1,158 @@
+// 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, imeiEquipmentId, logicalSlotId, runtimePath, } from '../domain/index.js';
+import { MODEM_IFACE, MODEM3GPP_IFACE } from './constants.js';
+import { findInterface, propValue, stringProp, } from './managed-objects.js';
+/** The prefix OUR udev rules use to label a slot in `Modem.Device`. */
+export const SLOT_UID_PREFIX = 'slot-';
+/**
+ * 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) {
+    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) {
+    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, slot) {
+    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) {
+    // Rung 1 — our slot-UID in `Device`.
+    if (looksLikeSlotUid(facts.device)) {
+        const device = facts.device;
+        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) {
+    const counts = new Map();
+    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 = duplicated
+            ? { ...facts, equipmentId: demoteToLowConfidence(equipmentId) }
+            : facts;
+        return resolveModemIdentity(resolvedFacts);
+    });
+}
+/** MM `Modem.Ports` is `a(su)`: entries of `[portName, portType]`. */
+function portNames(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const names = value
+        .map((entry) => (Array.isArray(entry) ? entry[0] : undefined))
+        .filter((name) => 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, modemPath) {
+    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 } : {}),
+    };
+}

package/dist/backend/identity-registry.d.ts

@@ -0,0 +1,51 @@
+import type { EquipmentId, LogicalSlotId, RuntimePath } from '../domain/index.js';
+import type { ResolvedIdentity } from './identity-ladder.js';
+/** 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;
+};
+/**
+ * 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 declare class IdentityRegistry {
+    #private;
+    /** A snapshot of the current logical rows, in insertion order. */
+    get rows(): IdentityRow[];
+    /** The row for a stable key, or `undefined`. */
+    get(stableKey: string): IdentityRow | undefined;
+    /** Drop a row (e.g. after a current-epoch removal). */
+    remove(stableKey: string): void;
+    /**
+     * 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;
+}

package/dist/backend/identity-registry.js

@@ -0,0 +1,101 @@
+// 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.
+const equipmentValue = (equipment) => 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 {
+    #rows = new Map();
+    /** A snapshot of the current logical rows, in insertion order. */
+    get rows() {
+        return [...this.#rows.values()];
+    }
+    /** The row for a stable key, or `undefined`. */
+    get(stableKey) {
+        return this.#rows.get(stableKey);
+    }
+    /** Drop a row (e.g. after a current-epoch removal). */
+    remove(stableKey) {
+        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) {
+        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, resolved, row) {
+        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) {
+        const { identity, stableKey } = resolved;
+        return {
+            stableKey,
+            equipmentId: identity.equipmentId,
+            runtimePath: identity.runtimePath,
+            ...(identity.logicalSlotId !== undefined ? { logicalSlotId: identity.logicalSlotId } : {}),
+        };
+    }
+    #findByEquipment(equipment, exceptKey) {
+        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/dist/backend/index.d.ts

@@ -0,0 +1,30 @@
+export { AT_BASELINE_ALLOWLIST, type AtAuditEntry, type AtAuditSink, AtCommandLease, type AtCommandLeaseDeps, AtCommandNotAllowedError, type AtCommandSender, AtCommandTimeoutError, type AtResponse, computeAtAllowlist, } from './at-lease.js';
+export { type CellInfoProvenance, type CellReading, compareServing, normalizeCellInfo, normalizeCellReading, selectServingCell, } from './cell-info.js';
+export { MM_BUS_NAME, MM_MANAGER_IFACE, MM_ROOT_PATH, MODEM_IFACE, MODEM_LOCATION_IFACE, MODEM3GPP_IFACE, MODEM3GPP_USSD_IFACE, SIM_IFACE, } from './constants.js';
+export { CELLULAR_USB_VENDOR_IDS, cellularEvidence, cellularVendorName, classifyDevice, classifyUsbNetDevice, type DeviceClass, type DeviceClassification, descriptorsMatch, detectUsbMode, modelLabel, publishesGenericIdentity, type UsbDeviceSnapshot, type UsbInterface, type UsbNetClass, type UsbNetClassification, unitDiscriminator, vendorLabel, } from './device-classifier.js';
+export { buildEnrichment, type EsimInfo, type EsimStatus, type ModemEnrichment, readEsimInfo, readRevision, type SimType, } from './enrichment.js';
+export { detectMmFeatures, detectModemFeatures, type MmFeatures, type MmPropertyProbe, type MmVersion, parseMmVersion, probeModemProperties, } from './features.js';
+export { looksLikeSlotUid, type ModemIdentityFacts, modemIdentityFactsFromTree, type ResolvedIdentity, resolveModemIdentities, resolveModemIdentity, SLOT_UID_PREFIX, type SlotSource, } from './identity-ladder.js';
+export { IdentityRegistry, type IdentityRow, type IdentityTransition, } from './identity-registry.js';
+export { ALLOW_ALL_INTERLOCK, type InterlockDecision, type InterlockTarget, type LifecycleInterlock, } from './lifecycle-interlock.js';
+export { asManagedObjects, type DecodedInterfaces, type DecodedManagedObjects, type DecodedObject, type DecodedProps, fetchManagedObjects, findInterface, findObject, followObjectPath, hasInterface, numberProp, objectPaths, pathsWithInterface, propValue, stringProp, } from './managed-objects.js';
+export { createMmDbusBackend, MmDbusBackend, type MmDbusBackendOptions, } from './mm-backend.js';
+export { decodeLocationSources, encodeLocationSources, MmLocation, type MmLocationDeps, } from './mm-location.js';
+export { MmMutations, type MmMutationsDeps } from './mm-mutations.js';
+export { ModemActor, NO_OP_QUIESCE, type QuiesceHook, type QuiesceLeaseHandle, type QuiesceTarget, } from './modem-actor.js';
+export { AUTO_APN_ADVISORY, type AutoApnAdvisory, type AutoApnTransitionResult, autoApnCapableFromVersion, autoApnSupportedByVersion, classifyActivation, type ManualApn, parseNmVersion, probeAutoApnCapability, toAutoArgs, toManualArgs, } from './nm-auto-apn.js';
+export { buildProfile, cliArg, createGsmArgs, flattenPairs, gsmFieldPairs, passwordFlags, patchPairs, } from './nm-gsm-fields.js';
+export { NmcliNmPort, type NmcliNmPortOptions, } from './nmcli-nm-port.js';
+export { type NmcliResult, type NmcliRunner, parseTerse, runNmcli, SpawnNmcliRunner, } from './nmcli-runner.js';
+export { createMmDbusObserver, type EpochRefreshEvent, MmDbusObserver, type MmDbusObserverOptions, } from './observer.js';
+export { NONE_POWER_CAPABILITY, NONE_POWER_HOOK, type PowerCapability, type PowerCapabilityKind, type PowerCycleContext, type PowerCycleResult, type PowerHook, type PreferredUsbMode, unsupportedPowerHook, } from './power-contract.js';
+export { attributeFault, attributeSnapshot, type FaultAttribution, type FaultSymptoms, symptomsFromSnapshot, } from './recovery-attribution.js';
+export { type BudgetDecision, beginAttempt, DEFAULT_RECOVERY_BUDGET, INITIAL_BUDGET_STATE, markRecovered, type RecoveryBudget, type RecoveryBudgetState, } from './recovery-budget.js';
+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.js';
+export { createRouterEthernetProbe, type RouterEthernetProbeDeps } from './router-ethernet.js';
+export { DEFAULT_SIGNAL_INTERVAL_SECONDS, type SignalCadence, SignalSetupManager, type SignalSetupManagerOptions, } from './signal-setup.js';
+export { sendSimPin, sendSimPuk } from './sim-unlock.js';
+export { ALLOW_ALL_TRANSITION_INTERLOCK, checkTransitionPreconditions, type InterlockHold, type PreconditionResult, type TransitionInterlock, type TransitionReadiness, type UsbModeTransitionOutcome, type UsbModeTransitionRequest, } from './transition-preconditions.js';
+export * from './usage/index.js';
+export { createUsbEnumerator, enumerateUsbDevices, parseUdevDatabase, type UsbEnumerator, type UsbEnumeratorDeps, } from './usb-enumerator.js';
+export { UsbModeTransition, type UsbModeTransitionDeps } from './usb-mode-transition.js';

package/dist/backend/index.js

@@ -0,0 +1,35 @@
+// 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, AtCommandLease, AtCommandNotAllowedError, AtCommandTimeoutError, computeAtAllowlist, } from './at-lease.js';
+export { compareServing, normalizeCellInfo, normalizeCellReading, selectServingCell, } from './cell-info.js';
+export { MM_BUS_NAME, MM_MANAGER_IFACE, MM_ROOT_PATH, MODEM_IFACE, MODEM_LOCATION_IFACE, MODEM3GPP_IFACE, MODEM3GPP_USSD_IFACE, SIM_IFACE, } from './constants.js';
+export { CELLULAR_USB_VENDOR_IDS, cellularEvidence, cellularVendorName, classifyDevice, classifyUsbNetDevice, descriptorsMatch, detectUsbMode, modelLabel, publishesGenericIdentity, unitDiscriminator, vendorLabel, } from './device-classifier.js';
+export { buildEnrichment, readEsimInfo, readRevision, } from './enrichment.js';
+export { detectMmFeatures, detectModemFeatures, parseMmVersion, probeModemProperties, } from './features.js';
+export { looksLikeSlotUid, modemIdentityFactsFromTree, resolveModemIdentities, resolveModemIdentity, SLOT_UID_PREFIX, } from './identity-ladder.js';
+export { IdentityRegistry, } from './identity-registry.js';
+export { ALLOW_ALL_INTERLOCK, } from './lifecycle-interlock.js';
+export { asManagedObjects, fetchManagedObjects, findInterface, findObject, followObjectPath, hasInterface, numberProp, objectPaths, pathsWithInterface, propValue, stringProp, } from './managed-objects.js';
+export { createMmDbusBackend, MmDbusBackend, } from './mm-backend.js';
+export { decodeLocationSources, encodeLocationSources, MmLocation, } from './mm-location.js';
+export { MmMutations } from './mm-mutations.js';
+export { ModemActor, NO_OP_QUIESCE, } from './modem-actor.js';
+export { AUTO_APN_ADVISORY, autoApnCapableFromVersion, autoApnSupportedByVersion, classifyActivation, parseNmVersion, probeAutoApnCapability, toAutoArgs, toManualArgs, } from './nm-auto-apn.js';
+export { buildProfile, cliArg, createGsmArgs, flattenPairs, gsmFieldPairs, passwordFlags, patchPairs, } from './nm-gsm-fields.js';
+export { NmcliNmPort, } from './nmcli-nm-port.js';
+export { parseTerse, runNmcli, SpawnNmcliRunner, } from './nmcli-runner.js';
+export { createMmDbusObserver, MmDbusObserver, } from './observer.js';
+export { NONE_POWER_CAPABILITY, NONE_POWER_HOOK, unsupportedPowerHook, } from './power-contract.js';
+export { attributeFault, attributeSnapshot, symptomsFromSnapshot, } from './recovery-attribution.js';
+export { beginAttempt, DEFAULT_RECOVERY_BUDGET, INITIAL_BUDGET_STATE, markRecovered, } from './recovery-budget.js';
+export { DEFAULT_LADDER_CONFIG, LADDER_ORDER, RecoveryLadder, } from './recovery-ladder.js';
+export { createRouterEthernetProbe } from './router-ethernet.js';
+export { DEFAULT_SIGNAL_INTERVAL_SECONDS, SignalSetupManager, } from './signal-setup.js';
+export { sendSimPin, sendSimPuk } from './sim-unlock.js';
+export { ALLOW_ALL_TRANSITION_INTERLOCK, checkTransitionPreconditions, } from './transition-preconditions.js';
+export * from './usage/index.js';
+export { createUsbEnumerator, enumerateUsbDevices, parseUdevDatabase, } from './usb-enumerator.js';
+export { UsbModeTransition } from './usb-mode-transition.js';

package/dist/backend/lifecycle-interlock.d.ts

@@ -0,0 +1,25 @@
+/** 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 declare const ALLOW_ALL_INTERLOCK: LifecycleInterlock;

package/dist/backend/lifecycle-interlock.js

@@ -0,0 +1,18 @@
+// 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.
+/**
+ * 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 = {
+    canDisrupt() {
+        return Promise.resolve({ allow: true });
+    },
+};

package/dist/backend/managed-objects.d.ts

@@ -0,0 +1,39 @@
+import type { DbusTransport, DbusValue, DbusVariant } from '../transport/index.js';
+/** 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 declare function asManagedObjects(value: DbusValue | undefined): DecodedManagedObjects;
+/** Call `ObjectManager.GetManagedObjects` on `destination` and decode the reply. */
+export declare function fetchManagedObjects(transport: DbusTransport, destination: string): Promise<DecodedManagedObjects>;
+/** Treat an `InterfacesAdded` body (`[path, interfaces]`) as one decoded object. */
+export declare function asAddedObject(path: DbusValue, interfaces: DbusValue): DecodedObject;
+/** Every object path in the tree, in wire order. */
+export declare function objectPaths(tree: DecodedManagedObjects): string[];
+/** The object at `path`, or `undefined`. */
+export declare function findObject(tree: DecodedManagedObjects, path: string): DecodedObject | undefined;
+/** The property entries of one interface on one object, or `undefined`. */
+export declare function findInterface(tree: DecodedManagedObjects, path: string, iface: string): DecodedProps | undefined;
+/** Object paths that carry a given interface. */
+export declare function pathsWithInterface(tree: DecodedManagedObjects, iface: string): string[];
+/** Whether an object exposes a given interface. */
+export declare function hasInterface(tree: DecodedManagedObjects, path: string, iface: string): boolean;
+/** The inner value of a property (a variant's `.value`), or `undefined`. */
+export declare function propValue(props: DecodedProps | undefined, name: string): DbusValue | undefined;
+/** A string-typed property, or `undefined` if absent / not a string. */
+export declare function stringProp(props: DecodedProps | undefined, name: string): string | undefined;
+/** A number-typed property, or `undefined` if absent / not a number. */
+export declare function numberProp(props: DecodedProps | undefined, name: string): number | undefined;
+/**
+ * A string-array (`as`) property, or `undefined` if absent / not an array. An
+ * EMPTY array answers `[]` — the device saying "none", a different fact from an
+ * absent property. Non-string members are dropped, never coerced.
+ */
+export declare function stringArrayProp(props: DecodedProps | undefined, name: string): readonly string[] | undefined;
+/** Resolve an object-path property (e.g. a modem's `Sim`) to that object's props. */
+export declare function followObjectPath(tree: DecodedManagedObjects, props: DecodedProps | undefined, propName: string, iface: string): DecodedProps | undefined;

package/dist/backend/managed-objects.js

@@ -0,0 +1,82 @@
+// 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 { MM_ROOT_PATH, OBJECT_MANAGER_IFACE } from './constants.js';
+/** Treat a `GetManagedObjects` reply body value as the decoded tree. */
+export function asManagedObjects(value) {
+    if (!Array.isArray(value)) {
+        throw new TypeError('managed-objects payload is not an array');
+    }
+    return value;
+}
+/** Call `ObjectManager.GetManagedObjects` on `destination` and decode the reply. */
+export async function fetchManagedObjects(transport, destination) {
+    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, interfaces) {
+    if (typeof path !== 'string' || !Array.isArray(interfaces)) {
+        throw new TypeError('InterfacesAdded body is not [objectPath, interfaces]');
+    }
+    return [path, interfaces];
+}
+/** Every object path in the tree, in wire order. */
+export function objectPaths(tree) {
+    return tree.map(([path]) => path);
+}
+/** The object at `path`, or `undefined`. */
+export function findObject(tree, path) {
+    return tree.find(([objectPath]) => objectPath === path);
+}
+/** The property entries of one interface on one object, or `undefined`. */
+export function findInterface(tree, path, iface) {
+    return findObject(tree, path)?.[1].find(([name]) => name === iface)?.[1];
+}
+/** Object paths that carry a given interface. */
+export function pathsWithInterface(tree, iface) {
+    return tree
+        .filter(([, interfaces]) => interfaces.some(([name]) => name === iface))
+        .map(([path]) => path);
+}
+/** Whether an object exposes a given interface. */
+export function hasInterface(tree, path, iface) {
+    return findInterface(tree, path, iface) !== undefined;
+}
+/** The inner value of a property (a variant's `.value`), or `undefined`. */
+export function propValue(props, name) {
+    return props?.find(([key]) => key === name)?.[1]?.value;
+}
+/** A string-typed property, or `undefined` if absent / not a string. */
+export function stringProp(props, name) {
+    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, name) {
+    const value = propValue(props, name);
+    return typeof value === 'number' ? value : undefined;
+}
+/**
+ * A string-array (`as`) property, or `undefined` if absent / not an array. An
+ * EMPTY array answers `[]` — the device saying "none", a different fact from an
+ * absent property. Non-string members are dropped, never coerced.
+ */
+export function stringArrayProp(props, name) {
+    const value = propValue(props, name);
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : undefined;
+}
+/** Resolve an object-path property (e.g. a modem's `Sim`) to that object's props. */
+export function followObjectPath(tree, props, propName, iface) {
+    const target = propValue(props, propName);
+    return typeof target === 'string' ? findInterface(tree, target, iface) : undefined;
+}

package/dist/backend/mapping.d.ts

@@ -0,0 +1,11 @@
+import { type CellularSnapshot } from '../domain/index.js';
+import { type DecodedManagedObjects } from './managed-objects.js';
+/** The dimensions of a mapped modem, WITHOUT a revision (the observer stamps that). */
+export type MappedModem = Omit<CellularSnapshot, 'revision'>;
+/** Map ONE modem object to its dimensions. The modem must expose `Modem`. */
+export declare function mapModem(tree: DecodedManagedObjects, modemPath: string): MappedModem;
+/** Every modem path in the tree (objects exposing the `Modem` interface), in order. */
+export declare function modemPaths(tree: DecodedManagedObjects): string[];
+/** A stable fingerprint of a mapped modem's meaningful dimensions (ignores revision
+ *  and source health), used to suppress redundant revision bumps on identical reads. */
+export declare function fingerprint(mapped: MappedModem): string;