@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/usb-mode/promotion-review.js

@@ -0,0 +1,87 @@
+// Rendering the REVIEW ARTIFACT for a catalog promotion — the PR-comment template.
+//
+// Catalog additions are human-reviewed commits (Phase-A rule). This module renders what
+// a reviewer reads: the proposed entry, the classifier fixture derived from the same
+// bundle, and a checklist whose boxes a machine cannot tick. It renders a REFUSAL with
+// equal prominence — a refused promotion produces a comment that says so, never silence,
+// because a silently-absent comment is indistinguishable from a forgotten run.
+//
+// Nothing here writes a file or opens a PR. The output is text.
+function refusalBlock(what, refusal) {
+    return [
+        `### ❌ ${what} — REFUSED`,
+        '',
+        `**Reason:** \`${refusal.reason}\``,
+        '',
+        `> ${refusal.detail}`,
+        '',
+        'This is a typed refusal from the ingestion seam, not a review opinion. Fix the',
+        'capture and re-run the runbook; do not hand-author the artifact around it.',
+    ].join('\n');
+}
+function entryBlock(entry) {
+    return [
+        '### Proposed `certified-catalog.json` entry',
+        '',
+        '```json',
+        JSON.stringify(entry, null, 2),
+        '```',
+    ].join('\n');
+}
+function fixtureBlock(fixture) {
+    const { snapshot, provenance } = fixture;
+    const syntheticNote = provenance.synthetic
+        ? '> ⚠️ Derived from a **synthetic** bundle — valid as test data, never as certification evidence.'
+        : `> Derived from a real capture, bundle sha256 \`${provenance.bundleSha256}\`.`;
+    return [
+        '### Proposed classifier fixture (`control/src/backend/device-classifier.test.ts`)',
+        '',
+        syntheticNote,
+        '',
+        '```ts',
+        `const FIXTURE: UsbDeviceSnapshot = ${JSON.stringify(snapshot, null, 2)};`,
+        '```',
+    ].join('\n');
+}
+function checklistBlock(context, entry) {
+    const transitions = entry.permittedTransitions.length;
+    return [
+        '### Reviewer checklist (every box is a human judgement)',
+        '',
+        `- [ ] The bundle at \`${context.evidencePath}\` was captured by **${context.runbook}** on real hardware, and its \`CERTIFY OK\` line reads \`synthetic=false\`.`,
+        '- [ ] The bundle sha256 in the entry matches the sha256 the capture printed — recomputed, not copied from this comment.',
+        `- [ ] \`canonicalMode: "${entry.canonicalMode}"\` is the mode the device was actually observed in, not the mode it was expected to be in.`,
+        transitions === 0
+            ? '- [ ] `permittedTransitions: []` is correct for this stage — a stage-1 entry never declares a transition.'
+            : '- [ ] The declared transition was OBSERVED end to end: the AT command executed, the port dropped if `expectsPortDrop`, and the device re-enumerated presenting `expectedDescriptors`.',
+        '- [ ] No claim in `docs/MODEM-SUPPORT-MATRIX.md` is being changed by this commit without its own evidence.',
+    ].join('\n');
+}
+/**
+ * Render the review comment for a promotion request. Always returns a comment: a
+ * refusal renders a refusal block, so a run that produced nothing promotable still
+ * leaves a visible, auditable trace.
+ */
+export function renderPromotionReview(request) {
+    const { context, entry, fixture } = request;
+    const parts = [
+        `## Catalog promotion review — ${context.runbook}`,
+        '',
+        `Evidence: \`${context.evidencePath}\``,
+        '',
+        'Generated by the `control/src/usb-mode/` ingestion seam. **This comment promotes',
+        'nothing** — the promotion is the human-reviewed commit that follows it.',
+        '',
+    ];
+    parts.push(entry.ok ? entryBlock(entry.value) : refusalBlock('Catalog entry', entry));
+    parts.push('');
+    parts.push(fixture.ok ? fixtureBlock(fixture.value) : refusalBlock('Classifier fixture', fixture));
+    parts.push('');
+    if (entry.ok) {
+        parts.push(checklistBlock(context, entry.value));
+    }
+    else {
+        parts.push('### No checklist', '', 'The catalog entry was refused, so there is nothing to review. A checklist here', 'would invite a reviewer to approve an artifact that does not exist.');
+    }
+    return `${parts.join('\n')}\n`;
+}

package/dist/usb-mode/usb-devices-parse.d.ts

@@ -0,0 +1,36 @@
+/** One interface line of a `usb-devices` record. */
+export interface ParsedUsbInterface {
+    readonly interfaceClass: number;
+    readonly interfaceSubClass: number;
+    readonly interfaceProtocol: number;
+    /** The bound kernel driver, omitted when `usb-devices` reports `(none)`. */
+    readonly driver?: string;
+}
+/** One device block of a `usb-devices` capture. */
+export interface ParsedUsbDevice {
+    /** Lowercase hex `xxxx:xxxx`, exactly the catalog's `vidPid` discriminator shape. */
+    readonly vidPid: string;
+    /** The `D:` line's `Cls=` byte — the device-descriptor `bDeviceClass`. */
+    readonly bDeviceClass: number;
+    readonly manufacturer?: string;
+    readonly product?: string;
+    readonly interfaces: readonly ParsedUsbInterface[];
+}
+/**
+ * Parse `usb-devices` output into one record per device. Pure and total: malformed
+ * lines are skipped rather than guessed at, and a block with no `P:` line yields no
+ * record (it has no identity, so inventing one would be a lie).
+ */
+export declare function parseUsbDevices(text: string): ParsedUsbDevice[];
+/**
+ * Find the single device matching `vidPid` in a parsed capture. Returns `undefined`
+ * when there is NO match, and — deliberately — also when there is more than one: a
+ * duplicate VID:PID (this bench has two identical Huawei HiLink units) makes the
+ * selection ambiguous, and an ambiguous selection must refuse rather than pick the
+ * first. The caller turns that into a typed refusal.
+ */
+export declare function selectUniqueDevice(devices: readonly ParsedUsbDevice[], vidPid: string): {
+    readonly device: ParsedUsbDevice;
+} | {
+    readonly ambiguousMatches: number;
+};

package/dist/usb-mode/usb-devices-parse.js

@@ -0,0 +1,157 @@
+// Parsing `usb-devices` text — the ONLY per-interface descriptor source inside a
+// certification bundle.
+//
+// A base certification bundle (`certify <slot>` with no `--transition`) carries no
+// structured descriptors at all: it holds `lsusb -v` and `usb-devices` as raw text plus
+// the slot's udev property map. Authoring a classifier fixture or a catalog entry from
+// such a bundle therefore requires reading the descriptors back out of that text, and
+// `usb-devices` is the right half to read — it is line-oriented, one fixed-width record
+// per device, and it names each interface's BOUND KERNEL DRIVER, which `lsusb -v` does
+// not. The driver is not optional detail here: `classifyDevice` decides `mm-managed` vs
+// `router-mode` partly on `qmi_wwan` / `cdc_ether` / `option` bindings.
+//
+// The parser is pure and total: unparseable lines are SKIPPED, never guessed at, and a
+// device that yields no interfaces still yields a record (callers decide whether an
+// interface-less device is usable — this file never makes that judgement).
+//
+// Record shape (`usb-devices`, one blank-line-separated block per device):
+//   T:  Bus=04 Lev=03 Prnt=03 Port=03 Cnt=01 Dev#=  7 Spd=480 MxCh= 0
+//   D:  Ver= 2.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=64 #Cfgs=  1
+//   P:  Vendor=2c7c ProdID=0801 Rev=05.04
+//   S:  Manufacturer=Quectel
+//   S:  Product=RM530N-GL
+//   I:  If#= 4 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=qmi_wwan
+/** Read `Key=value` from a `usb-devices` line; `undefined` when the key is absent. */
+function field(line, key) {
+    // Values are whitespace-delimited and may be preceded by padding spaces (`Dev#=  7`).
+    // `Cls=ff(vend.)` carries a trailing gloss, stripped by the hex/number parsers below.
+    const match = new RegExp(`${key}=\\s*(\\S+)`).exec(line);
+    return match?.[1];
+}
+/** Parse a hex byte field, tolerating `usb-devices`' `ff(vend.)` gloss suffix. */
+function hexByte(line, key) {
+    const raw = field(line, key);
+    if (raw === undefined) {
+        return undefined;
+    }
+    const digits = /^[0-9a-fA-F]{1,2}/.exec(raw)?.[0];
+    if (digits === undefined) {
+        return undefined;
+    }
+    const value = Number.parseInt(digits, 16);
+    return Number.isNaN(value) ? undefined : value;
+}
+/** Parse an `S:  Manufacturer=…` style line into its `[key, value]` pair. */
+function stringField(line) {
+    const eq = line.indexOf('=');
+    if (eq < 0) {
+        return undefined;
+    }
+    const key = line.slice(3, eq).trim();
+    const value = line.slice(eq + 1).trim();
+    return key === '' || value === '' ? undefined : [key, value];
+}
+function emptyAccumulator() {
+    return { interfaces: [] };
+}
+function finish(acc, out) {
+    // A record with no `P:` line is not a device — never synthesise an identity for it.
+    if (acc.vidPid === undefined) {
+        return;
+    }
+    out.push({
+        vidPid: acc.vidPid,
+        bDeviceClass: acc.bDeviceClass ?? 0,
+        interfaces: acc.interfaces,
+        ...(acc.manufacturer !== undefined ? { manufacturer: acc.manufacturer } : {}),
+        ...(acc.product !== undefined ? { product: acc.product } : {}),
+    });
+}
+function applyProductLine(line, acc) {
+    const vendor = field(line, 'Vendor');
+    const product = field(line, 'ProdID');
+    if (vendor !== undefined && product !== undefined) {
+        acc.vidPid = `${vendor.toLowerCase()}:${product.toLowerCase()}`;
+    }
+}
+function applyStringLine(line, acc) {
+    const pair = stringField(line);
+    if (pair === undefined) {
+        return;
+    }
+    const [key, value] = pair;
+    if (key === 'Manufacturer') {
+        acc.manufacturer = value;
+    }
+    else if (key === 'Product') {
+        acc.product = value;
+    }
+}
+function applyInterfaceLine(line, acc) {
+    const interfaceClass = hexByte(line, 'Cls');
+    const interfaceSubClass = hexByte(line, 'Sub');
+    const interfaceProtocol = hexByte(line, 'Prot');
+    if (interfaceClass === undefined ||
+        interfaceSubClass === undefined ||
+        interfaceProtocol === undefined) {
+        return;
+    }
+    const driver = field(line, 'Driver');
+    acc.interfaces.push({
+        interfaceClass,
+        interfaceSubClass,
+        interfaceProtocol,
+        ...(driver !== undefined && driver !== '(none)' ? { driver } : {}),
+    });
+}
+/**
+ * Parse `usb-devices` output into one record per device. Pure and total: malformed
+ * lines are skipped rather than guessed at, and a block with no `P:` line yields no
+ * record (it has no identity, so inventing one would be a lie).
+ */
+export function parseUsbDevices(text) {
+    const out = [];
+    let acc = emptyAccumulator();
+    for (const line of text.split('\n')) {
+        // A `T:` line opens a new device record; `usb-devices` also blank-line-separates
+        // them, but the topology line is the reliable delimiter (blank lines are optional
+        // in some kernels' output).
+        if (line.startsWith('T:')) {
+            finish(acc, out);
+            acc = emptyAccumulator();
+            continue;
+        }
+        if (line.startsWith('D:')) {
+            const deviceClass = hexByte(line, 'Cls');
+            if (deviceClass !== undefined) {
+                acc.bDeviceClass = deviceClass;
+            }
+        }
+        else if (line.startsWith('P:')) {
+            applyProductLine(line, acc);
+        }
+        else if (line.startsWith('S:')) {
+            applyStringLine(line, acc);
+        }
+        else if (line.startsWith('I:')) {
+            applyInterfaceLine(line, acc);
+        }
+    }
+    finish(acc, out);
+    return out;
+}
+/**
+ * Find the single device matching `vidPid` in a parsed capture. Returns `undefined`
+ * when there is NO match, and — deliberately — also when there is more than one: a
+ * duplicate VID:PID (this bench has two identical Huawei HiLink units) makes the
+ * selection ambiguous, and an ambiguous selection must refuse rather than pick the
+ * first. The caller turns that into a typed refusal.
+ */
+export function selectUniqueDevice(devices, vidPid) {
+    const matches = devices.filter((d) => d.vidPid === vidPid);
+    const only = matches[0];
+    if (matches.length === 1 && only !== undefined) {
+        return { device: only };
+    }
+    return { ambiguousMatches: matches.length };
+}

package/dist/ussd/calls.d.ts

@@ -0,0 +1,32 @@
+import type { DbusTransport } from '../transport/index.js';
+import type { UssdRepliedState } from './session.js';
+/** `MMModem3gppUssdSessionState`. */
+export declare const USSD_STATE_UNKNOWN = 0;
+export declare const USSD_STATE_IDLE = 1;
+export declare const USSD_STATE_ACTIVE = 2;
+export declare const USSD_STATE_USER_RESPONSE = 3;
+/**
+ * Decode MM's post-call session state. `UNKNOWN` folds onto `released` with the
+ * rest: an unreadable state must close the session rather than leave the operator
+ * looking at a dialogue nothing can advance.
+ */
+export declare function decodeRepliedState(state: number): UssdRepliedState;
+export interface UssdCallTarget {
+    readonly transport: DbusTransport;
+    readonly destination: string;
+    readonly modem: string;
+    readonly timeoutMs: number;
+}
+export declare function callInitiate(target: UssdCallTarget, ussdCommand: string): Promise<string>;
+export declare function callRespond(target: UssdCallTarget, ussdResponse: string): Promise<string>;
+export declare function callCancel(target: UssdCallTarget): Promise<void>;
+/**
+ * Read the post-call session state.
+ *
+ * A targeted `Properties.Get` rather than a `GetManagedObjects` sweep: this runs
+ * after every network round-trip, and the whole-tree read is the most expensive
+ * call in the package. `unknown` on anything unreadable — the caller treats that
+ * as "the network released the session", which is the conservative direction (it
+ * closes a session rather than leaving one the operator cannot see).
+ */
+export declare function readUssdState(target: UssdCallTarget): Promise<number>;

package/dist/ussd/calls.js

@@ -0,0 +1,96 @@
+// The four D-Bus calls the USSD adapter makes, and nothing else.
+//
+// Split from the adapter so the session machinery above can be read without the
+// marshalling below, and so a call's shape (interface, member, signature) is
+// stated once in one place.
+//
+// CARRIER TEXT DISCIPLINE: `Initiate` and `Respond` both take and return operator
+// text, and neither the command nor the reply may ever reach a log line. Nothing
+// in this file logs, and every error raised here is re-thrown untouched so the
+// classifier — not a string built around the payload — decides what the caller is
+// told.
+import { MODEM3GPP_USSD_IFACE, PROPERTIES_IFACE } from '../backend/constants.js';
+/** `MMModem3gppUssdSessionState`. */
+export const USSD_STATE_UNKNOWN = 0;
+export const USSD_STATE_IDLE = 1;
+export const USSD_STATE_ACTIVE = 2;
+export const USSD_STATE_USER_RESPONSE = 3;
+/**
+ * Decode MM's post-call session state. `UNKNOWN` folds onto `released` with the
+ * rest: an unreadable state must close the session rather than leave the operator
+ * looking at a dialogue nothing can advance.
+ */
+export function decodeRepliedState(state) {
+    if (state === USSD_STATE_USER_RESPONSE) {
+        return 'awaiting-reply';
+    }
+    return state === USSD_STATE_ACTIVE ? 'active' : 'released';
+}
+function firstString(body) {
+    const value = body[0];
+    return typeof value === 'string' ? value : '';
+}
+export async function callInitiate(target, ussdCommand) {
+    const reply = await target.transport.callMethod({
+        destination: target.destination,
+        path: target.modem,
+        interface: MODEM3GPP_USSD_IFACE,
+        member: 'Initiate',
+        signature: 's',
+        args: [ussdCommand],
+        timeoutMs: target.timeoutMs,
+    });
+    return firstString(reply.body);
+}
+export async function callRespond(target, ussdResponse) {
+    const reply = await target.transport.callMethod({
+        destination: target.destination,
+        path: target.modem,
+        interface: MODEM3GPP_USSD_IFACE,
+        member: 'Respond',
+        signature: 's',
+        args: [ussdResponse],
+        timeoutMs: target.timeoutMs,
+    });
+    return firstString(reply.body);
+}
+export async function callCancel(target) {
+    await target.transport.callMethod({
+        destination: target.destination,
+        path: target.modem,
+        interface: MODEM3GPP_USSD_IFACE,
+        member: 'Cancel',
+        timeoutMs: target.timeoutMs,
+    });
+}
+/**
+ * Read the post-call session state.
+ *
+ * A targeted `Properties.Get` rather than a `GetManagedObjects` sweep: this runs
+ * after every network round-trip, and the whole-tree read is the most expensive
+ * call in the package. `unknown` on anything unreadable — the caller treats that
+ * as "the network released the session", which is the conservative direction (it
+ * closes a session rather than leaving one the operator cannot see).
+ */
+export async function readUssdState(target) {
+    try {
+        const reply = await target.transport.callMethod({
+            destination: target.destination,
+            path: target.modem,
+            interface: PROPERTIES_IFACE,
+            member: 'Get',
+            signature: 'ss',
+            args: [MODEM3GPP_USSD_IFACE, 'State'],
+            timeoutMs: target.timeoutMs,
+        });
+        const wrapped = reply.body[0];
+        if (typeof wrapped === 'number') {
+            return wrapped;
+        }
+        const inner = wrapped?.value;
+        return typeof inner === 'number' ? inner : USSD_STATE_UNKNOWN;
+    }
+    catch {
+        return USSD_STATE_UNKNOWN;
+    }
+}

package/dist/ussd/index.d.ts

@@ -0,0 +1,5 @@
+export { callCancel, callInitiate, callRespond, decodeRepliedState, readUssdState, USSD_STATE_ACTIVE, USSD_STATE_IDLE, USSD_STATE_UNKNOWN, USSD_STATE_USER_RESPONSE, type UssdCallTarget, } from './calls.js';
+export { MmUssd, type MmUssdDeps, type UssdScheduler, type UssdTimerHandle, type UssdVerbResult, } from './mm-ussd.js';
+export { classifyUssdFailure, isPacketSwitchedOnly, USSD_REFUSAL_REASONS, type UssdRefusalReason, type UssdRegistrationFacts, } from './refusal.js';
+export { decodeAccessTechnologies, readUssdRegistrationFacts, registrationFactsFromTree, UNKNOWN_REGISTRATION, } from './registration.js';
+export { IDLE_SESSION, isUssdSessionOpen, reduceUssdSession, USSD_SESSION_OUTCOMES, USSD_SESSION_STATES, type UssdRepliedState, type UssdSessionEvent, type UssdSessionOutcome, type UssdSessionSnapshot, type UssdSessionState, type UssdTransition, } from './session.js';

package/dist/ussd/index.js

@@ -0,0 +1,12 @@
+// The gated USSD capability module — session state machine, refusal taxonomy, and
+// the ModemManager `Modem3gpp.Ussd` adapter.
+//
+// GATED: nothing here runs unless the operator has enabled the `ussd` capability
+// module and the modem positively advertises the interface (`../capability`).
+// LEASE-ONLY: a USSD session cannot re-register the radio, so it takes the
+// per-modem mutation lease and is NOT journaled.
+export { callCancel, callInitiate, callRespond, decodeRepliedState, readUssdState, USSD_STATE_ACTIVE, USSD_STATE_IDLE, USSD_STATE_UNKNOWN, USSD_STATE_USER_RESPONSE, } from './calls.js';
+export { MmUssd, } from './mm-ussd.js';
+export { classifyUssdFailure, isPacketSwitchedOnly, USSD_REFUSAL_REASONS, } from './refusal.js';
+export { decodeAccessTechnologies, readUssdRegistrationFacts, registrationFactsFromTree, UNKNOWN_REGISTRATION, } from './registration.js';
+export { IDLE_SESSION, isUssdSessionOpen, reduceUssdSession, USSD_SESSION_OUTCOMES, USSD_SESSION_STATES, } from './session.js';

package/dist/ussd/mm-ussd.d.ts

@@ -0,0 +1,37 @@
+import type { ModemActor } from '../backend/modem-actor.js';
+import type { ModemRef } from '../ports/index.js';
+import type { DbusTransport } from '../transport/index.js';
+import { type UssdRefusalReason } from './refusal.js';
+import { type UssdSessionSnapshot } from './session.js';
+export interface UssdTimerHandle {
+    cancel(): void;
+}
+export type UssdScheduler = (delayMs: number, run: () => void) => UssdTimerHandle;
+export interface UssdVerbResult {
+    readonly ok: boolean;
+    readonly snapshot: UssdSessionSnapshot;
+    /** Carrier text. Redacted by key everywhere it is serialized. */
+    readonly ussdReply?: string;
+    readonly refusal?: UssdRefusalReason;
+}
+export interface MmUssdDeps {
+    readonly transport: DbusTransport;
+    readonly actor: ModemActor;
+    readonly destination?: string;
+    readonly resolveStableKey: (modem: ModemRef) => string;
+    readonly callTimeoutMs?: number;
+    readonly sessionIdleTimeoutMs?: number;
+    readonly scheduler?: UssdScheduler;
+    /** Notified on every stored-state change, so a UI can follow a session. */
+    readonly onSessionChange?: (stableKey: string, snapshot: UssdSessionSnapshot) => void;
+}
+export declare class MmUssd {
+    #private;
+    constructor(deps: MmUssdDeps);
+    snapshot(modem: ModemRef): UssdSessionSnapshot;
+    initiate(modem: ModemRef, ussdCommand: string): Promise<UssdVerbResult>;
+    respond(modem: ModemRef, ussdResponse: string): Promise<UssdVerbResult>;
+    cancel(modem: ModemRef): Promise<UssdVerbResult>;
+    /** Drop every timer. A live session on the modem is NOT cancelled by this. */
+    stop(): void;
+}

package/dist/ussd/mm-ussd.js

@@ -0,0 +1,205 @@
+// The ModemManager USSD adapter — `Modem3gpp.Ussd` driven by the pure session
+// machine in `./session`.
+//
+// Three properties are load-bearing and none of them is obvious from the D-Bus
+// API alone:
+//
+//  1. **Every verb runs through the shared per-modem `ModemActor`.** A USSD
+//     session is a single network-side resource per subscriber, so two verbs
+//     interleaving on one modem is exactly the double-dialogue the network
+//     answers busy. The actor is keyed on the STABLE key, so the serialization
+//     survives a replug like every other disruptive op in this package.
+//
+//  2. **An unanswered session is closed at a bound, and the CANCEL is attempted.**
+//     A session nobody responds to stays open NETWORK-side; letting it expire in
+//     silence would leave the next `Initiate` failing busy for reasons the
+//     operator cannot see. The bound closes our machine and best-effort releases
+//     the network's — best-effort because a modem that did not answer the last
+//     call may not answer this one either, and a timeout must still terminate.
+//
+//  3. **A `closed` session resets the STORED state to idle, while the CALLER is
+//     told `closed`.** The machine is deliberately terminal so a finished session
+//     cannot be resurrected; the adapter's map is per-modem and long-lived, so it
+//     starts each new dialogue from a fresh machine.
+//
+// The carrier's text rides `ussdReply` and NOTHING here logs it. That field name
+// is not cosmetic: `../redact` is key-based, so the name IS what guarantees the
+// value is masked in every receipt, bundle, and log line it can reach.
+import { MM_BUS_NAME } from '../backend/constants.js';
+import { callCancel, callInitiate, callRespond, decodeRepliedState, readUssdState, } from './calls.js';
+import { classifyUssdFailure } from './refusal.js';
+import { readUssdRegistrationFacts } from './registration.js';
+import { IDLE_SESSION, reduceUssdSession, } from './session.js';
+/** A network round-trip. USSD legitimately takes tens of seconds. */
+const DEFAULT_CALL_TIMEOUT_MS = 45_000;
+/** How long a session may sit awaiting an operator response before it is closed. */
+const DEFAULT_SESSION_IDLE_TIMEOUT_MS = 120_000;
+const defaultScheduler = (delayMs, run) => {
+    const timer = setTimeout(run, delayMs);
+    timer.unref?.();
+    return {
+        cancel: () => {
+            clearTimeout(timer);
+        },
+    };
+};
+export class MmUssd {
+    #deps;
+    #destination;
+    #callTimeoutMs;
+    #idleTimeoutMs;
+    #scheduler;
+    #sessions = new Map();
+    #timers = new Map();
+    constructor(deps) {
+        this.#deps = deps;
+        this.#destination = deps.destination ?? MM_BUS_NAME;
+        this.#callTimeoutMs = deps.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+        this.#idleTimeoutMs = deps.sessionIdleTimeoutMs ?? DEFAULT_SESSION_IDLE_TIMEOUT_MS;
+        this.#scheduler = deps.scheduler ?? defaultScheduler;
+    }
+    snapshot(modem) {
+        return this.#sessions.get(this.#deps.resolveStableKey(modem)) ?? IDLE_SESSION;
+    }
+    initiate(modem, ussdCommand) {
+        return this.#runVerb(modem, { kind: 'initiate' }, (target) => callInitiate(target, ussdCommand));
+    }
+    respond(modem, ussdResponse) {
+        return this.#runVerb(modem, { kind: 'respond' }, (target) => callRespond(target, ussdResponse));
+    }
+    cancel(modem) {
+        const key = this.#deps.resolveStableKey(modem);
+        return this.#deps.actor.run(key, async () => {
+            const gate = this.#gate(key, { kind: 'cancel' });
+            if (!gate.ok) {
+                return gate.result;
+            }
+            const target = this.#target(modem);
+            try {
+                await callCancel(target);
+                return this.#settle(key, { kind: 'cancelled' });
+            }
+            catch (error) {
+                return this.#fail(key, modem, error);
+            }
+        });
+    }
+    /** Drop every timer. A live session on the modem is NOT cancelled by this. */
+    stop() {
+        for (const timer of this.#timers.values()) {
+            timer.cancel();
+        }
+        this.#timers.clear();
+    }
+    async #runVerb(modem, event, dispatch) {
+        const key = this.#deps.resolveStableKey(modem);
+        return this.#deps.actor.run(key, async () => {
+            const gate = this.#gate(key, event);
+            if (!gate.ok) {
+                return gate.result;
+            }
+            const target = this.#target(modem);
+            try {
+                const ussdReply = await dispatch(target);
+                const sessionState = decodeRepliedState(await readUssdState(target));
+                const settled = this.#settle(key, { kind: 'replied', sessionState });
+                // A session the network kept open — whether or not it asked a
+                // question — is what the idle bound exists to release.
+                if (sessionState !== 'released') {
+                    this.#armIdleTimeout(key, modem);
+                }
+                return { ...settled, ussdReply };
+            }
+            catch (error) {
+                return this.#fail(key, modem, error);
+            }
+        });
+    }
+    /**
+     * Apply the operator's verb to the machine. A refusal is returned WITHOUT
+     * touching the stored state or dialling the bus — a doomed verb must not
+     * disturb a live session.
+     */
+    #gate(key, event) {
+        const current = this.#sessions.get(key) ?? IDLE_SESSION;
+        const transition = reduceUssdSession(current, event);
+        if (!transition.ok) {
+            return {
+                ok: false,
+                result: { ok: false, snapshot: current, refusal: transition.refusal },
+            };
+        }
+        this.#store(key, transition.snapshot);
+        return { ok: true };
+    }
+    #settle(key, event) {
+        const current = this.#sessions.get(key) ?? IDLE_SESSION;
+        const transition = reduceUssdSession(current, event);
+        if (!transition.ok) {
+            return { ok: false, snapshot: current, refusal: transition.refusal };
+        }
+        this.#store(key, transition.snapshot);
+        const closedRefusal = transition.snapshot.refusal;
+        return {
+            ok: closedRefusal === undefined,
+            snapshot: transition.snapshot,
+            ...(closedRefusal === undefined ? {} : { refusal: closedRefusal }),
+        };
+    }
+    async #fail(key, modem, error) {
+        const registration = await readUssdRegistrationFacts(this.#deps.transport, this.#destination, modem);
+        return this.#settle(key, { kind: 'failed', reason: classifyUssdFailure(error, registration) });
+    }
+    /**
+     * A session reaching `closed` is REPORTED as closed and STORED as idle, so the
+     * next `initiate` starts from a fresh machine rather than the terminal one.
+     */
+    #store(key, snapshot) {
+        this.#clearTimer(key);
+        if (snapshot.state === 'closed') {
+            this.#sessions.delete(key);
+        }
+        else {
+            this.#sessions.set(key, snapshot);
+        }
+        this.#deps.onSessionChange?.(key, snapshot);
+    }
+    #armIdleTimeout(key, modem) {
+        this.#clearTimer(key);
+        this.#timers.set(key, this.#scheduler(this.#idleTimeoutMs, () => {
+            void this.#expire(key, modem);
+        }));
+    }
+    #clearTimer(key) {
+        this.#timers.get(key)?.cancel();
+        this.#timers.delete(key);
+    }
+    /**
+     * The bound elapsed. The machine closes `timed-out` FIRST — that outcome is
+     * the operator's answer whether or not the release lands — and the modem-side
+     * cancel is attempted afterwards, best-effort.
+     */
+    async #expire(key, modem) {
+        await this.#deps.actor.run(key, async () => {
+            if (!this.#sessions.has(key)) {
+                return;
+            }
+            this.#settle(key, { kind: 'timeout' });
+            try {
+                await callCancel(this.#target(modem));
+            }
+            catch {
+                // The modem that did not answer the dialogue may not answer this
+                // either; the session is already closed on our side.
+            }
+        });
+    }
+    #target(modem) {
+        return {
+            transport: this.#deps.transport,
+            destination: this.#destination,
+            modem,
+            timeoutMs: this.#callTimeoutMs,
+        };
+    }
+}