@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/backend/usage/sampler.js

@@ -0,0 +1,211 @@
+// The usage sampler — orchestrates the counter source, pure accounting reducer,
+// billing-cycle math, and fail-soft persistence into one internal service.
+//
+// SESSION = the kernel boot id. Interface byte counters reset to zero on reboot, so
+// the boot id both scopes every baseline key AND lets a reload detect a reboot: a
+// persisted document from a different boot keeps its per-cycle totals but drops its
+// baselines, so the first post-reboot sample re-baselines zero-delta.
+//
+// PERSISTENCE: state is written at most once per minute (rate-limited) plus a
+// `flush()` shutdown hook. A crash therefore loses AT MOST ~1 minute of unpersisted
+// deltas (the window since the last rate-limited write); a clean shutdown calls
+// `flush()` and loses effectively nothing.
+import { epochMillis } from '../../domain/index.js';
+import { applySample, initialAccount } from './accounting.js';
+import { cycleStart } from './billing-cycle.js';
+import { USAGE_SCHEMA_VERSION } from './store.js';
+const DEFAULT_PERSIST_INTERVAL_MS = 60_000;
+const DEFAULT_CYCLE_DAY = 1;
+function toPersistedSlot(logicalSlotId, account) {
+    return {
+        logicalSlotId,
+        cycleBytes: account.cycleBytes,
+        cycleStartMs: account.cycleStartMs,
+        ...(account.key !== undefined
+            ? { mappingGeneration: account.key.mappingGeneration, ifname: account.key.ifname }
+            : {}),
+        ...(account.lastObserved !== undefined ? { lastObserved: account.lastObserved } : {}),
+    };
+}
+export class UsageSampler {
+    #bootId;
+    #source;
+    #store;
+    #now;
+    #persistIntervalMs;
+    #defaultCycleDay;
+    #accounts = new Map();
+    #policies = new Map();
+    // Policies written through `applyUsagePolicy` OUTRANK whatever an observation
+    // carries, for the life of the process. Without this, the next `sample()` would
+    // clobber a just-applied write with the policy the composition root happened to
+    // build its observation from — and the operator would watch their setting
+    // revert. The durable store is the source of truth for both, so an override and
+    // an observation can only ever disagree inside that window.
+    #policyOverrides = new Map();
+    #lastPersistMs;
+    #dirty = false;
+    constructor(options, initial) {
+        this.#bootId = options.bootId;
+        this.#source = options.source;
+        this.#store = options.store;
+        this.#now = options.now ?? Date.now;
+        this.#persistIntervalMs = options.persistIntervalMs ?? DEFAULT_PERSIST_INTERVAL_MS;
+        this.#defaultCycleDay = options.defaultCycleDay ?? DEFAULT_CYCLE_DAY;
+        this.#lastPersistMs = this.#now();
+        this.#hydrate(initial);
+    }
+    /** Load persisted state (recreating a fresh file if absent/corrupt) then build the sampler. */
+    static async create(options) {
+        const now = options.now ?? Date.now;
+        const initial = await options.store.load(options.bootId, now());
+        return new UsageSampler(options, initial);
+    }
+    /** Rebuild in-memory accounts. A reboot (differing boot id) drops the baselines. */
+    #hydrate(initial) {
+        const sameBoot = initial.bootId === this.#bootId;
+        for (const slot of initial.slots) {
+            const canResume = sameBoot &&
+                slot.ifname !== undefined &&
+                slot.mappingGeneration !== undefined &&
+                slot.lastObserved !== undefined;
+            if (canResume) {
+                const key = {
+                    logicalSlotId: slot.logicalSlotId,
+                    mappingGeneration: slot.mappingGeneration,
+                    ifname: slot.ifname,
+                    bootId: this.#bootId,
+                };
+                this.#accounts.set(slot.logicalSlotId, {
+                    cycleBytes: slot.cycleBytes,
+                    cycleStartMs: slot.cycleStartMs,
+                    paused: false,
+                    key,
+                    lastObserved: slot.lastObserved,
+                });
+            }
+            else {
+                this.#accounts.set(slot.logicalSlotId, {
+                    cycleBytes: slot.cycleBytes,
+                    cycleStartMs: slot.cycleStartMs,
+                    paused: false,
+                });
+            }
+        }
+    }
+    /** Take one sampling pass over the current counters for the given observations. */
+    async sample(observations) {
+        const counters = await this.#source.read();
+        const now = this.#now();
+        for (const obs of observations) {
+            const slotId = obs.logicalSlotId;
+            const usage = this.#policyOverrides.get(slotId) ?? obs.usage;
+            this.#policies.set(slotId, usage);
+            const cycleDay = usage.cycleDay ?? this.#defaultCycleDay;
+            const cycleStartMs = cycleStart(epochMillis(now), cycleDay);
+            const current = counters.get(obs.ifname);
+            if (current === undefined) {
+                // No reading for this interface — ensure the slot exists, attribute nothing.
+                if (!this.#accounts.has(slotId)) {
+                    this.#accounts.set(slotId, initialAccount(cycleStartMs));
+                }
+                continue;
+            }
+            const key = {
+                logicalSlotId: slotId,
+                mappingGeneration: obs.mappingGeneration,
+                ifname: obs.ifname,
+                bootId: this.#bootId,
+            };
+            const next = applySample(this.#accounts.get(slotId), {
+                key,
+                current,
+                confidence: obs.confidence,
+                cycleStartMs,
+            });
+            this.#accounts.set(slotId, next);
+        }
+        this.#dirty = true;
+        await this.#maybePersist(now);
+    }
+    /** Current per-slot usage — the queryable snapshot the CLI and platform read. */
+    snapshot() {
+        const generatedAtMs = this.#now();
+        const slots = [];
+        for (const [slotId, account] of this.#accounts) {
+            const policy = this.#policies.get(slotId);
+            const thresholdBytes = policy?.thresholdBytes;
+            slots.push({
+                logicalSlotId: slotId,
+                cycleBytes: account.cycleBytes,
+                cycleStartMs: account.cycleStartMs,
+                paused: account.paused,
+                ...(policy?.cycleDay !== undefined ? { cycleDay: policy.cycleDay } : {}),
+                ...(thresholdBytes !== undefined ? { thresholdBytes } : {}),
+                thresholdExceeded: thresholdBytes !== undefined && account.cycleBytes > thresholdBytes,
+            });
+        }
+        return { bootId: this.#bootId, generatedAtMs, slots };
+    }
+    /**
+     * Apply an operator's usage policy to this slot immediately, without waiting
+     * for the next sampling pass.
+     *
+     * A CHANGED CYCLE ANCHOR RESTARTS THE WINDOW AT ZERO, and keeps the counter
+     * BASELINE. Those two halves are the honest answer to a question with no
+     * truthful one: bytes already accrued were measured under the OLD window, so
+     * carrying them into the new one over-reports it, and there is no record of
+     * how they were distributed within it. Starting fresh states plainly that the
+     * new window began now; keeping `lastObserved` means the next sample still
+     * attributes only genuinely new bytes, never a jump. A threshold-only change
+     * moves no anchor and therefore resets nothing.
+     */
+    applyUsagePolicy(logicalSlotId, usage, atMs) {
+        const now = atMs ?? this.#now();
+        this.#policyOverrides.set(logicalSlotId, usage);
+        this.#policies.set(logicalSlotId, usage);
+        const cycleStartMs = cycleStart(epochMillis(now), usage.cycleDay ?? this.#defaultCycleDay);
+        const account = this.#accounts.get(logicalSlotId);
+        if (account === undefined) {
+            this.#accounts.set(logicalSlotId, initialAccount(cycleStartMs));
+            this.#dirty = true;
+            return { cycleStartMs, cycleReset: false };
+        }
+        if (account.cycleStartMs === cycleStartMs) {
+            return { cycleStartMs, cycleReset: false };
+        }
+        this.#accounts.set(logicalSlotId, { ...account, cycleBytes: 0, cycleStartMs });
+        this.#dirty = true;
+        return { cycleStartMs, cycleReset: true };
+    }
+    /** Flush unpersisted state immediately — the shutdown hook (bounds loss to ≤1 min). */
+    async flush() {
+        if (this.#dirty) {
+            await this.#persist(this.#now());
+        }
+    }
+    async #maybePersist(now) {
+        if (now - this.#lastPersistMs >= this.#persistIntervalMs) {
+            await this.#persist(now);
+        }
+    }
+    async #persist(now) {
+        const slots = [];
+        for (const [slotId, account] of this.#accounts) {
+            slots.push(toPersistedSlot(slotId, account));
+        }
+        const state = {
+            schemaVersion: USAGE_SCHEMA_VERSION,
+            bootId: this.#bootId,
+            savedAtMs: now,
+            slots,
+        };
+        await this.#store.save(state);
+        this.#lastPersistMs = now;
+        this.#dirty = false;
+    }
+}
+/** Load persisted state and build a ready sampler. See `UsageSampler.create`. */
+export function createUsageSampler(options) {
+    return UsageSampler.create(options);
+}

package/dist/backend/usage/store.d.ts

@@ -0,0 +1,38 @@
+/** The current on-disk schema version. Bump when the persisted shape changes. */
+export declare const USAGE_SCHEMA_VERSION = 1;
+/** One slot's persisted accounting row — opaque ids and numbers only. */
+export interface PersistedSlot {
+    readonly logicalSlotId: string;
+    readonly cycleBytes: number;
+    readonly cycleStartMs: number;
+    readonly mappingGeneration?: number;
+    readonly ifname?: string;
+    readonly lastObserved?: number;
+}
+/** The full persisted document. `bootId` scopes the baselines to one kernel session. */
+export interface PersistedUsage {
+    readonly schemaVersion: typeof USAGE_SCHEMA_VERSION;
+    readonly bootId: string;
+    readonly savedAtMs: number;
+    readonly slots: readonly PersistedSlot[];
+}
+/** A metadata-only log event. Corruption NEVER carries the raw file content. */
+export type UsageLogEvent = {
+    readonly kind: 'corrupt-state';
+    readonly bytes: number;
+    readonly reason: string;
+};
+/** Sink for sampler log events. Defaults to a metadata-only `console.warn`. */
+export type UsageLogger = (event: UsageLogEvent) => void;
+/** The persistence seam the sampler drives. */
+export interface UsageStore {
+    /** Load persisted state; recreate a fresh 0600 file if absent or corrupt. */
+    load(currentBootId: string, nowMs: number): Promise<PersistedUsage>;
+    /** Atomically write state with mode 0600 (temp → chmod → rename). */
+    save(state: PersistedUsage): Promise<void>;
+}
+export interface UsageFileStoreOptions {
+    readonly path: string;
+    readonly logger?: UsageLogger;
+}
+export declare function createUsageFileStore(options: UsageFileStoreOptions): UsageStore;

package/dist/backend/usage/store.js

@@ -0,0 +1,126 @@
+// Versioned, fail-soft persistence for the usage sampler.
+//
+// The persisted file is a small JSON document carrying ONLY opaque slot ids,
+// interface names, and numbers — never any subscriber/device identity (no ICCID,
+// IMSI, IMEI, operator or model). By construction the sampler holds no such fields,
+// and `no-pii.test.ts` proves the serialized bytes stay clean.
+//
+// Two hard guarantees:
+//   - MODE 0600: the file is written to a temp path, chmod'd to 0600 AFTER the
+//     write, then atomically renamed over the target — so the on-disk file always
+//     ends up owner-read/write-only regardless of the process umask.
+//   - FAIL-SOFT ON CORRUPTION: an unparseable/incompatible file is never fatal. We
+//     log METADATA ONLY (byte length + a classification reason — never the raw,
+//     possibly-sensitive content), recreate a fresh empty 0600 file, and carry on.
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** The current on-disk schema version. Bump when the persisted shape changes. */
+export const USAGE_SCHEMA_VERSION = 1;
+function defaultLogger(event) {
+    console.warn(`[usage-sampler] ${event.kind}: bytes=${event.bytes} reason=${event.reason}`);
+}
+function freshState(bootId, nowMs) {
+    return { schemaVersion: USAGE_SCHEMA_VERSION, bootId, savedAtMs: nowMs, slots: [] };
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function validateSlot(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new SchemaError('slot');
+    }
+    const slot = raw;
+    if (typeof slot.logicalSlotId !== 'string') {
+        throw new SchemaError('logicalSlotId');
+    }
+    if (!isFiniteNumber(slot.cycleBytes) || !isFiniteNumber(slot.cycleStartMs)) {
+        throw new SchemaError('cycleBytes|cycleStartMs');
+    }
+    return {
+        logicalSlotId: slot.logicalSlotId,
+        cycleBytes: slot.cycleBytes,
+        cycleStartMs: slot.cycleStartMs,
+        ...(isFiniteNumber(slot.mappingGeneration)
+            ? { mappingGeneration: slot.mappingGeneration }
+            : {}),
+        ...(typeof slot.ifname === 'string' ? { ifname: slot.ifname } : {}),
+        ...(isFiniteNumber(slot.lastObserved) ? { lastObserved: slot.lastObserved } : {}),
+    };
+}
+/** Parse + validate the document. Throws `SchemaError` (metadata-only) on mismatch. */
+function validate(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new SchemaError('document');
+    }
+    const doc = raw;
+    if (doc.schemaVersion !== USAGE_SCHEMA_VERSION) {
+        throw new SchemaError('schemaVersion');
+    }
+    if (typeof doc.bootId !== 'string' || !isFiniteNumber(doc.savedAtMs)) {
+        throw new SchemaError('bootId|savedAtMs');
+    }
+    if (!Array.isArray(doc.slots)) {
+        throw new SchemaError('slots');
+    }
+    return {
+        schemaVersion: USAGE_SCHEMA_VERSION,
+        bootId: doc.bootId,
+        savedAtMs: doc.savedAtMs,
+        slots: doc.slots.map(validateSlot),
+    };
+}
+/** A schema violation naming only the offending FIELD (never file content). */
+class SchemaError extends Error {
+    constructor(field) {
+        super(`schema-mismatch: ${field}`);
+    }
+}
+/** Classify a load failure into a metadata-only reason string (no raw content). */
+function classifyFailure(error) {
+    if (error instanceof SchemaError) {
+        return error.message;
+    }
+    if (error instanceof SyntaxError) {
+        const offset = /position (\d+)/.exec(error.message)?.[1];
+        return offset !== undefined ? `invalid-json at offset ${offset}` : 'invalid-json';
+    }
+    return 'unreadable';
+}
+export function createUsageFileStore(options) {
+    const logger = options.logger ?? defaultLogger;
+    const { path } = options;
+    async function writeAtomic(state) {
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp`;
+        await writeFile(tmp, JSON.stringify(state));
+        // chmod AFTER the write (not an open flag) so mode is 0600 regardless of umask.
+        await chmod(tmp, 0o600);
+        await rename(tmp, path);
+    }
+    return {
+        async load(currentBootId, nowMs) {
+            let text;
+            try {
+                text = await readFile(path, 'utf8');
+            }
+            catch {
+                // Absent (or unreadable) → start empty; the first save lays down a 0600 file.
+                return freshState(currentBootId, nowMs);
+            }
+            try {
+                return validate(JSON.parse(text));
+            }
+            catch (error) {
+                logger({
+                    kind: 'corrupt-state',
+                    bytes: Buffer.byteLength(text, 'utf8'),
+                    reason: classifyFailure(error),
+                });
+                const fresh = freshState(currentBootId, nowMs);
+                await writeAtomic(fresh);
+                return fresh;
+            }
+        },
+        save: writeAtomic,
+    };
+}

package/dist/backend/usb-device-snapshot.d.ts

@@ -0,0 +1,31 @@
+/** One USB interface's descriptor bytes plus its bound kernel driver, if any. */
+export interface UsbInterface {
+    readonly interfaceClass: number;
+    readonly interfaceSubClass: number;
+    readonly interfaceProtocol: number;
+    /** The bound kernel driver (`qmi_wwan`, `cdc_mbim`, `option`, `cdc_ether`, …). */
+    readonly driver?: string;
+}
+/** A single USB device as observed from udev/sysfs — the classifier's whole input. */
+export interface UsbDeviceSnapshot {
+    readonly vendorId: string;
+    readonly productId: string;
+    readonly model?: string;
+    readonly firmwareRevision?: string;
+    readonly manufacturer?: string;
+    readonly product?: string;
+    readonly databaseVendor?: string;
+    readonly databaseModel?: string;
+    readonly serialNumber?: string;
+    /** The device-descriptor `bDeviceClass` byte (0 ⇒ class is per-interface). */
+    readonly bDeviceClass: number;
+    readonly interfaces: readonly UsbInterface[];
+    /** Stable physical-topology UID (udev `ID_PATH` / physdev) — survives a mode change. */
+    readonly physicalUid?: string;
+    /** Absolute sysfs path for the USB device, derived from udev's `P:` record. */
+    readonly sysfsPath?: string;
+    /** The bound network interface name, if the device presents one (`wwan0`, `usb0`). */
+    readonly ifname?: string;
+    /** Raw udev properties (`ID_USB_MODESWITCH`, `ID_MM_CANDIDATE`, …). */
+    readonly udevProperties?: Readonly<Record<string, string>>;
+}

package/dist/backend/usb-device-snapshot.js

@@ -0,0 +1 @@
+export {};

package/dist/backend/usb-enumerator.d.ts

@@ -0,0 +1,21 @@
+import type { UsbDeviceSnapshot } from './device-classifier.js';
+/** The injectable dependencies for the enumerator. */
+export interface UsbEnumeratorDeps {
+    /** Provides the raw `udevadm info --export-db` text. Defaults to a `Bun.spawn` call. */
+    readonly readUdevDatabase?: () => Promise<string>;
+}
+/** A refresh-triggered USB device enumerator. */
+export interface UsbEnumerator {
+    /** Snapshot current USB state — re-reads udev every call (never cached). */
+    enumerate(): Promise<readonly UsbDeviceSnapshot[]>;
+}
+/**
+ * Parse `udevadm info --export-db` output into device snapshots. Pure and exported so
+ * the production parse is unit-testable against canned udev text. Interface drivers
+ * are stitched from each `usb_interface` record onto its parent `usb_device`.
+ */
+export declare function parseUdevDatabase(text: string): UsbDeviceSnapshot[];
+/** Create a refresh-triggered USB enumerator over an injectable udev reader. */
+export declare function createUsbEnumerator(deps?: UsbEnumeratorDeps): UsbEnumerator;
+/** Convenience: enumerate current USB devices once via the default udev reader. */
+export declare function enumerateUsbDevices(): Promise<readonly UsbDeviceSnapshot[]>;

package/dist/backend/usb-enumerator.js

@@ -0,0 +1,153 @@
+// Production USB enumeration — a refresh-triggered snapshot of udev/sysfs state.
+//
+// `enumerate()` shells out to `udevadm info --export-db` (via `Bun.spawn`) each call
+// — it is deliberately NOT cached, so a caller re-reads current state after a hot-plug
+// or a mode switch. The raw-database read is an injectable seam (`readUdevDatabase`)
+// so tests drive canned udev output with no real hardware, and the parser itself is a
+// pure, exported function. udev exports every interface's class/subclass/protocol on
+// the parent device as `ID_USB_INTERFACES` (`:ff0000:0a0000:` …), and each interface's
+// bound DRIVER on its own `usb_interface` record — this parser stitches the two.
+async function defaultReadUdevDatabase() {
+    const proc = Bun.spawn(['udevadm', 'info', '--export-db'], { stdout: 'pipe', stderr: 'pipe' });
+    const [stdout, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+    if (exitCode !== 0) {
+        const stderr = await new Response(proc.stderr).text();
+        throw new Error(`udevadm info --export-db exited ${exitCode}: ${stderr.trim()}`);
+    }
+    return stdout;
+}
+function parseRecords(text) {
+    const records = [];
+    let devpath = '';
+    let env = new Map();
+    const flush = () => {
+        if (env.size > 0 || devpath !== '') {
+            records.push({ devpath, env });
+        }
+        devpath = '';
+        env = new Map();
+    };
+    for (const line of text.split('\n')) {
+        if (line.trim() === '') {
+            flush();
+            continue;
+        }
+        const kind = line.slice(0, 2);
+        const rest = line.slice(3);
+        if (kind === 'P:') {
+            devpath = rest;
+        }
+        else if (kind === 'E:') {
+            const eq = rest.indexOf('=');
+            if (eq > 0) {
+                env.set(rest.slice(0, eq), rest.slice(eq + 1));
+            }
+        }
+    }
+    flush();
+    return records;
+}
+/** Parse an `ID_USB_INTERFACES` value (`:ff0000:0a0000:`) into class/subclass/protocol triples. */
+function parseInterfaces(value) {
+    if (value === undefined) {
+        return [];
+    }
+    const interfaces = [];
+    for (const token of value.split(':')) {
+        if (token.length !== 6) {
+            continue;
+        }
+        interfaces.push({
+            interfaceClass: Number.parseInt(token.slice(0, 2), 16),
+            interfaceSubClass: Number.parseInt(token.slice(2, 4), 16),
+            interfaceProtocol: Number.parseInt(token.slice(4, 6), 16),
+        });
+    }
+    return interfaces;
+}
+function interfaceIndex(devpath) {
+    const dot = devpath.lastIndexOf('.');
+    if (dot < 0) {
+        return undefined;
+    }
+    const index = Number.parseInt(devpath.slice(dot + 1), 10);
+    return Number.isNaN(index) ? undefined : index;
+}
+function buildSnapshot(devpath, env) {
+    const vendorId = env.get('ID_VENDOR_ID');
+    const productId = env.get('ID_MODEL_ID');
+    if (vendorId === undefined || productId === undefined) {
+        return undefined;
+    }
+    const props = {};
+    for (const [key, value] of env) {
+        props[key] = value;
+    }
+    const model = env.get('ID_MODEL');
+    const firmwareRevision = env.get('ID_REVISION');
+    const physicalUid = env.get('ID_PATH');
+    return {
+        vendorId,
+        productId,
+        sysfsPath: `/sys${devpath}`,
+        bDeviceClass: 0,
+        interfaces: parseInterfaces(env.get('ID_USB_INTERFACES')),
+        udevProperties: props,
+        ...(model !== undefined ? { model } : {}),
+        ...(firmwareRevision !== undefined ? { firmwareRevision } : {}),
+        ...(physicalUid !== undefined ? { physicalUid } : {}),
+    };
+}
+/**
+ * Parse `udevadm info --export-db` output into device snapshots. Pure and exported so
+ * the production parse is unit-testable against canned udev text. Interface drivers
+ * are stitched from each `usb_interface` record onto its parent `usb_device`.
+ */
+export function parseUdevDatabase(text) {
+    const records = parseRecords(text);
+    const devices = new Map();
+    const snapshots = new Map();
+    for (const record of records) {
+        if (record.env.get('DEVTYPE') !== 'usb_device') {
+            continue;
+        }
+        const snapshot = buildSnapshot(record.devpath, record.env);
+        if (snapshot !== undefined) {
+            snapshots.set(record.devpath, snapshot);
+            devices.set(record.devpath, [...snapshot.interfaces]);
+        }
+    }
+    for (const record of records) {
+        if (record.env.get('DEVTYPE') !== 'usb_interface') {
+            continue;
+        }
+        const driver = record.env.get('DRIVER');
+        const index = interfaceIndex(record.devpath);
+        if (driver === undefined || index === undefined) {
+            continue;
+        }
+        const parent = record.devpath.slice(0, record.devpath.lastIndexOf('/'));
+        const ifaces = devices.get(parent);
+        const iface = ifaces?.[index];
+        if (ifaces !== undefined && iface !== undefined) {
+            ifaces[index] = { ...iface, driver };
+        }
+    }
+    return [...snapshots.entries()].map(([devpath, snapshot]) => ({
+        ...snapshot,
+        interfaces: devices.get(devpath) ?? snapshot.interfaces,
+    }));
+}
+/** Create a refresh-triggered USB enumerator over an injectable udev reader. */
+export function createUsbEnumerator(deps = {}) {
+    const read = deps.readUdevDatabase ?? defaultReadUdevDatabase;
+    return {
+        async enumerate() {
+            return parseUdevDatabase(await read());
+        },
+    };
+}
+/** Convenience: enumerate current USB devices once via the default udev reader. */
+export function enumerateUsbDevices() {
+    return createUsbEnumerator().enumerate();
+}

package/dist/backend/usb-mode-transition.d.ts

@@ -0,0 +1,29 @@
+import type { DeviceIfname, ModemManagerPort, NetworkManagerPort } from '../ports/index.js';
+import { type CertifiedCatalog } from '../usb-mode/index.js';
+import { type AtAuditSink, type AtCommandSender } from './at-lease.js';
+import { type UsbDeviceSnapshot } from './device-classifier.js';
+import type { ModemActor } from './modem-actor.js';
+import { type TransitionInterlock, type UsbModeTransitionOutcome, type UsbModeTransitionRequest } from './transition-preconditions.js';
+/** Construction dependencies for the transition. Everything I/O is injectable. */
+export interface UsbModeTransitionDeps {
+    readonly actor: ModemActor;
+    readonly nm: NetworkManagerPort;
+    readonly modemManager: Pick<ModemManagerPort, 'inhibit' | 'uninhibit'>;
+    readonly atSender: AtCommandSender;
+    /** Refresh-triggered USB enumeration (e.g. `createUsbEnumerator().enumerate`). */
+    readonly enumerate: () => Promise<readonly UsbDeviceSnapshot[]>;
+    readonly interlock?: TransitionInterlock;
+    readonly catalog?: CertifiedCatalog;
+    readonly audit?: AtAuditSink;
+    readonly resolveIfname?: (device: UsbDeviceSnapshot) => DeviceIfname | undefined;
+    readonly watchdogMs?: number;
+    readonly reenumerationTimeoutMs?: number;
+    readonly pollIntervalMs?: number;
+}
+/** The USB-mode transition transaction. One instance is reusable across requests. */
+export declare class UsbModeTransition {
+    #private;
+    constructor(deps: UsbModeTransitionDeps);
+    /** Run one transition. Preconditions are checked at entry, then again in-actor. */
+    execute(request: UsbModeTransitionRequest): Promise<UsbModeTransitionOutcome>;
+}