@ceralive/modem-control 1.0.0 → 1.2.0

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,
+        };
+    }
+}

package/dist/ussd/refusal.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Every way a USSD verb can fail to do what the operator asked.
+ *
+ *   unsupported          — this modem exposes no USSD interface at all.
+ *   lte-only-unsupported — the modem is registered PS-only (LTE/5G with no CS
+ *                          domain) and the network refused. NOT a device fault.
+ *   carrier-rejected     — the network refused for some other reason.
+ *   not-registered       — there is no network to carry the session.
+ *   session-busy         — a session is already open (locally or network-side).
+ *   no-session           — respond/cancel with nothing open.
+ *   invalid-state        — the verb is wrong for the state the session is in.
+ *   timeout              — the bounded wait elapsed with no answer.
+ *   transport-failed     — the bus call itself failed; the modem never answered.
+ */
+export declare const USSD_REFUSAL_REASONS: readonly ['unsupported', 'lte-only-unsupported', 'carrier-rejected', 'not-registered', 'session-busy', 'no-session', 'invalid-state', 'timeout', 'transport-failed'];
+export type UssdRefusalReason = (typeof USSD_REFUSAL_REASONS)[number];
+/**
+ * What the modem is registered on, as far as anyone has looked.
+ *
+ * `csDomain` is the load-bearing field: `false` means the modem is attached with
+ * NO circuit-switched domain available (LTE/5G-SA without CSFB), which is the
+ * registration on which a plain USSD refusal is a carrier-policy statement rather
+ * than a device one. `undefined` means nobody read it, and is never treated as
+ * `false`.
+ */
+export interface UssdRegistrationFacts {
+    readonly registered: boolean;
+    /** Is a circuit-switched domain available on this registration? */
+    readonly csDomain?: boolean;
+    /** MM access technologies currently in use, lowercased (`lte`, `5gnr`, …). */
+    readonly accessTechnologies?: readonly string[];
+}
+/**
+ * True when the modem's registration positively cannot carry a circuit-switched
+ * service. Requires evidence in BOTH directions: something must say the CS domain
+ * is absent, and every technology in use must be a packet-only one. A modem that
+ * reported no technologies at all answers `false` — an empty list is a statement
+ * about the read.
+ */
+export declare function isPacketSwitchedOnly(facts: UssdRegistrationFacts): boolean;
+/**
+ * Classify a failed USSD call. Pure, total, never throws.
+ *
+ * Order is deliberate: the D-Bus error NAME is the strongest signal and is read
+ * first; the message text is consulted only for the names MM overloads; anything
+ * unrecognised stays `transport-failed`, which is the honest answer for a failure
+ * whose origin cannot be attributed to the network.
+ *
+ * The PS-only promotion runs LAST and applies to exactly the two reasons that are
+ * ambiguous between a device limit and a carrier policy — a `not-registered` or a
+ * bus failure is neither, and is left alone.
+ */
+export declare function classifyUssdFailure(error: unknown, registration?: UssdRegistrationFacts): UssdRefusalReason;

package/dist/ussd/refusal.js

@@ -0,0 +1,154 @@
+// Why a USSD verb did not succeed — one typed vocabulary, and the classifier that
+// maps ModemManager's own failure surface onto it.
+//
+// The point of typing these is that every member names a DIFFERENT thing the
+// operator can do, and the one this module exists for is the honest reporting of
+// a carrier that will not carry USSD at all on the registration the modem has.
+//
+// THE LTE-ONLY CASE, stated plainly. USSD is a circuit-switched supplementary
+// service. A modem registered PS-only — LTE or 5G-SA with no CS domain and no
+// CSFB — can only carry it if the operator deploys USSI (USSD over IMS, 3GPP TS
+// 24.390); many do not, and the modem/network then answers a generic
+// unsupported/failed error that is indistinguishable, on its face, from "this
+// modem has no USSD interface". Reporting that as a device limitation would send
+// an operator hunting for a firmware fix for a network policy, so the classifier
+// takes the modem's REGISTRATION alongside the error and separates the two.
+//
+// Nothing here guesses: `lte-only-unsupported` is claimed ONLY when the
+// registration is positively known to be PS-only. An unknown registration keeps
+// the generic reason, because "we did not look" is not evidence.
+/**
+ * Every way a USSD verb can fail to do what the operator asked.
+ *
+ *   unsupported          — this modem exposes no USSD interface at all.
+ *   lte-only-unsupported — the modem is registered PS-only (LTE/5G with no CS
+ *                          domain) and the network refused. NOT a device fault.
+ *   carrier-rejected     — the network refused for some other reason.
+ *   not-registered       — there is no network to carry the session.
+ *   session-busy         — a session is already open (locally or network-side).
+ *   no-session           — respond/cancel with nothing open.
+ *   invalid-state        — the verb is wrong for the state the session is in.
+ *   timeout              — the bounded wait elapsed with no answer.
+ *   transport-failed     — the bus call itself failed; the modem never answered.
+ */
+export const USSD_REFUSAL_REASONS = [
+    'unsupported',
+    'lte-only-unsupported',
+    'carrier-rejected',
+    'not-registered',
+    'session-busy',
+    'no-session',
+    'invalid-state',
+    'timeout',
+    'transport-failed',
+];
+/** Access technologies that carry no circuit-switched domain of their own. */
+const PACKET_ONLY_RATS = new Set([
+    'lte',
+    '5gnr',
+    'lte-cat-m',
+    'lte-nb-iot',
+]);
+/**
+ * True when the modem's registration positively cannot carry a circuit-switched
+ * service. Requires evidence in BOTH directions: something must say the CS domain
+ * is absent, and every technology in use must be a packet-only one. A modem that
+ * reported no technologies at all answers `false` — an empty list is a statement
+ * about the read.
+ */
+export function isPacketSwitchedOnly(facts) {
+    if (!facts.registered) {
+        return false;
+    }
+    if (facts.csDomain !== false) {
+        return false;
+    }
+    const rats = facts.accessTechnologies;
+    if (rats === undefined || rats.length === 0) {
+        return false;
+    }
+    return rats.every((rat) => PACKET_ONLY_RATS.has(rat.toLowerCase()));
+}
+/**
+ * ModemManager D-Bus error names this classifier recognises, matched on the
+ * SUFFIX after the last dot so a future `...Error.Core.Unsupported` regrouping
+ * does not silently fall through to `transport-failed`.
+ */
+const ERROR_SUFFIX_REASONS = new Map([
+    ['Unsupported', 'unsupported'],
+    ['NotSupported', 'unsupported'],
+    ['InProgress', 'session-busy'],
+    ['NoNetwork', 'not-registered'],
+    ['NotRegistered', 'not-registered'],
+    ['Timeout', 'timeout'],
+    ['Aborted', 'carrier-rejected'],
+    ['Failed', 'carrier-rejected'],
+]);
+/**
+ * Message fragments that identify a refusal no error NAME distinguishes. MM
+ * folds several modem answers into `Core.Failed`, so the text is the only signal
+ * separating "the network said no" from "the bus call broke".
+ */
+const MESSAGE_REASONS = [
+    [/ussd.*(?:not supported|unsupported)/i, 'unsupported'],
+    [/(?:session|operation) (?:already )?(?:active|in progress)/i, 'session-busy'],
+    [/no (?:active )?ussd session/i, 'no-session'],
+    [/not registered|no network/i, 'not-registered'],
+    [/timed? ?out/i, 'timeout'],
+    [/rejected|refused|denied|network error/i, 'carrier-rejected'],
+];
+function errorName(error) {
+    if (typeof error !== 'object' || error === null) {
+        return undefined;
+    }
+    const name = error.dbusName;
+    if (typeof name === 'string' && name.includes('.')) {
+        return name;
+    }
+    const fallback = error.name;
+    return typeof fallback === 'string' && fallback.includes('.') ? fallback : undefined;
+}
+function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'object' && error !== null) {
+        const message = error.message;
+        if (typeof message === 'string') {
+            return message;
+        }
+    }
+    return String(error);
+}
+/**
+ * Classify a failed USSD call. Pure, total, never throws.
+ *
+ * Order is deliberate: the D-Bus error NAME is the strongest signal and is read
+ * first; the message text is consulted only for the names MM overloads; anything
+ * unrecognised stays `transport-failed`, which is the honest answer for a failure
+ * whose origin cannot be attributed to the network.
+ *
+ * The PS-only promotion runs LAST and applies to exactly the two reasons that are
+ * ambiguous between a device limit and a carrier policy — a `not-registered` or a
+ * bus failure is neither, and is left alone.
+ */
+export function classifyUssdFailure(error, registration = { registered: false }) {
+    const name = errorName(error);
+    const suffix = name?.slice(name.lastIndexOf('.') + 1);
+    const message = errorMessage(error);
+    let reason = suffix === undefined ? undefined : ERROR_SUFFIX_REASONS.get(suffix);
+    // `Core.Failed` is MM's catch-all, so its message is worth more than its name.
+    if (reason === undefined || reason === 'carrier-rejected') {
+        for (const [pattern, mapped] of MESSAGE_REASONS) {
+            if (pattern.test(message)) {
+                reason = mapped;
+                break;
+            }
+        }
+    }
+    if (reason === undefined) {
+        return 'transport-failed';
+    }
+    const ambiguous = reason === 'unsupported' || reason === 'carrier-rejected';
+    return ambiguous && isPacketSwitchedOnly(registration) ? 'lte-only-unsupported' : reason;
+}

package/dist/ussd/registration.d.ts

@@ -0,0 +1,20 @@
+import { type DecodedManagedObjects } from '../backend/managed-objects.js';
+import type { DbusTransport } from '../transport/index.js';
+import type { UssdRegistrationFacts } from './refusal.js';
+/** Decode `Modem.AccessTechnologies` into the technology names in use. */
+export declare function decodeAccessTechnologies(mask: number): readonly string[];
+/**
+ * Derive the registration facts from an already-fetched managed-objects tree.
+ *
+ * Pure, so the derivation is testable against a fixture tree without a bus — the
+ * `sim-unlock.ts` split between "read the tree" and "decide from the tree".
+ */
+export declare function registrationFactsFromTree(tree: DecodedManagedObjects, modemPath: string): UssdRegistrationFacts;
+/** The unread default — every field withheld, so nothing can be claimed from it. */
+export declare const UNKNOWN_REGISTRATION: UssdRegistrationFacts;
+/**
+ * Read the registration facts for one modem. Fail-soft: a tree we could not fetch
+ * yields {@link UNKNOWN_REGISTRATION}, which can only ever make the refusal LESS
+ * specific.
+ */
+export declare function readUssdRegistrationFacts(transport: DbusTransport, destination: string, modemPath: string): Promise<UssdRegistrationFacts>;

package/dist/ussd/registration.js

@@ -0,0 +1,101 @@
+// Reading the registration facts the USSD refusal classifier needs.
+//
+// ModemManager publishes NO "is a circuit-switched domain available" property, so
+// the fact has to be DERIVED — and the derivation is worth stating, because it is
+// the difference between telling an operator their modem cannot do USSD and
+// telling them their carrier will not carry it on this registration:
+//
+//   * `Modem.AccessTechnologies` is a bitmask. When every bit in use is a
+//     packet-only radio (LTE, 5G-NR, LTE-M, NB-IoT) the modem is not camped on a
+//     circuit-switched radio at all.
+//   * `Modem3gpp.RegistrationState` still overrides that, because CS FALLBACK is
+//     exactly the case where an LTE-camped modem CAN reach the CS domain. MM has
+//     two states that say so outright — `HOME_CSFB_NOT_PREFERRED` (9) and
+//     `ROAMING_CSFB_NOT_PREFERRED` (10) — and a modem in either of them is
+//     reported CS-capable regardless of its radio.
+//
+// Both reads are best-effort and NEVER throw: a fact nobody could read is left
+// `undefined`, which the classifier treats as "we did not look" rather than as a
+// negative. That asymmetry is the whole safety property — an unread registration
+// can only ever produce the generic refusal, never the more specific claim.
+import { MODEM_IFACE, MODEM3GPP_IFACE } from '../backend/constants.js';
+import { fetchManagedObjects, findInterface, numberProp, } from '../backend/managed-objects.js';
+/** `MMModemAccessTechnology` bits this module names. */
+const ACCESS_TECHNOLOGY_BITS = [
+    [1 << 1, 'gsm'],
+    [1 << 2, 'gsm-compact'],
+    [1 << 3, 'gprs'],
+    [1 << 4, 'edge'],
+    [1 << 5, 'umts'],
+    [1 << 6, 'hsdpa'],
+    [1 << 7, 'hsupa'],
+    [1 << 8, 'hspa'],
+    [1 << 9, 'hspa-plus'],
+    [1 << 10, '1xrtt'],
+    [1 << 11, 'evdo0'],
+    [1 << 12, 'evdoa'],
+    [1 << 13, 'evdob'],
+    [1 << 14, 'lte'],
+    [1 << 15, '5gnr'],
+    [1 << 16, 'lte-cat-m'],
+    [1 << 17, 'lte-nb-iot'],
+];
+/** `MMModem3gppRegistrationState` values that mean the modem is on a network. */
+const REGISTERED_STATES = new Set([1, 5, 6, 7, 9, 10]);
+/** …and the two that positively advertise a circuit-switched fallback. */
+const CSFB_STATES = new Set([9, 10]);
+/** Decode `Modem.AccessTechnologies` into the technology names in use. */
+export function decodeAccessTechnologies(mask) {
+    const names = [];
+    for (const [bit, name] of ACCESS_TECHNOLOGY_BITS) {
+        if ((mask & bit) !== 0) {
+            names.push(name);
+        }
+    }
+    return names;
+}
+/**
+ * Derive the registration facts from an already-fetched managed-objects tree.
+ *
+ * Pure, so the derivation is testable against a fixture tree without a bus — the
+ * `sim-unlock.ts` split between "read the tree" and "decide from the tree".
+ */
+export function registrationFactsFromTree(tree, modemPath) {
+    const modem = findInterface(tree, modemPath, MODEM_IFACE);
+    const threeGpp = findInterface(tree, modemPath, MODEM3GPP_IFACE);
+    const registrationState = numberProp(threeGpp, 'RegistrationState');
+    const accessMask = numberProp(modem, 'AccessTechnologies');
+    const registered = registrationState !== undefined && REGISTERED_STATES.has(registrationState);
+    const technologies = accessMask === undefined ? undefined : decodeAccessTechnologies(accessMask);
+    // A CSFB registration is CS-capable outright. Otherwise the domain is only
+    // declared ABSENT when the radios in use were actually read and are all
+    // packet-only; an unread mask leaves the field undefined on purpose.
+    let csDomain;
+    if (registrationState !== undefined && CSFB_STATES.has(registrationState)) {
+        csDomain = true;
+    }
+    else if (technologies !== undefined && technologies.length > 0) {
+        csDomain = technologies.some((rat) => rat !== 'lte' && rat !== '5gnr' && rat !== 'lte-cat-m' && rat !== 'lte-nb-iot');
+    }
+    return {
+        registered,
+        ...(csDomain === undefined ? {} : { csDomain }),
+        ...(technologies === undefined ? {} : { accessTechnologies: technologies }),
+    };
+}
+/** The unread default — every field withheld, so nothing can be claimed from it. */
+export const UNKNOWN_REGISTRATION = { registered: false };
+/**
+ * Read the registration facts for one modem. Fail-soft: a tree we could not fetch
+ * yields {@link UNKNOWN_REGISTRATION}, which can only ever make the refusal LESS
+ * specific.
+ */
+export async function readUssdRegistrationFacts(transport, destination, modemPath) {
+    try {
+        const tree = await fetchManagedObjects(transport, destination);
+        return registrationFactsFromTree(tree, modemPath);
+    }
+    catch {
+        return UNKNOWN_REGISTRATION;
+    }
+}

package/dist/ussd/session.d.ts

@@ -0,0 +1,106 @@
+import type { UssdRefusalReason } from './refusal.js';
+/**
+ * Session states.
+ *
+ * Three of them (`idle`, `active`, `awaiting-reply`) mirror MM's own
+ * `MMModem3gppUssdSessionState`; the rest are LOCAL in-flight states, because MM
+ * has no state for "we dispatched a call and the reply has not landed". Without
+ * them a second `initiate` racing the first would be judged against `idle` and
+ * allowed through, which is exactly the double-open the network answers busy.
+ */
+export declare const USSD_SESSION_STATES: readonly [
+/** No session. MM `IDLE`. */
+'idle', 
+/** `Initiate` dispatched, reply outstanding. Local. */
+'initiating', 
+/** Network answered and the session is open with nothing pending. MM `ACTIVE`. */
+'active', 
+/** Network asked a question; a `Respond` is required. MM `USER_RESPONSE`. */
+'awaiting-reply', 
+/** `Respond` dispatched, reply outstanding. Local. */
+'responding', 
+/** `Cancel` dispatched, confirmation outstanding. Local. */
+'cancelling', 
+/** Terminal for this session object. A new session starts from a new machine. */
+'closed'];
+export type UssdSessionState = (typeof USSD_SESSION_STATES)[number];
+/** How a session that reached `closed` got there. */
+export declare const USSD_SESSION_OUTCOMES: readonly [
+/** The network completed the dialogue and released the session. */
+'completed', 
+/** The operator cancelled it. */
+'cancelled', 
+/** No answer within the bound; the machine closed it locally. */
+'timed-out', 
+/** The network or the modem refused. `refusal` names which. */
+'failed'];
+export type UssdSessionOutcome = (typeof USSD_SESSION_OUTCOMES)[number];
+/** MM's post-call session state, decoded. */
+export type UssdRepliedState = 'awaiting-reply' | 'active' | 'released';
+export type UssdSessionEvent = 
+/** The operator asked to open a session. */
+{
+    readonly kind: 'initiate';
+}
+/** The operator answered a network prompt. */
+ | {
+    readonly kind: 'respond';
+}
+/** The operator asked to close the session. */
+ | {
+    readonly kind: 'cancel';
+}
+/**
+ * The network answered an `Initiate`/`Respond`. `sessionState` is MM's own
+ * post-call `Modem3gpp.Ussd.State`, decoded: the network either wants an
+ * answer, is holding the session open with nothing pending, or released it.
+ */
+ | {
+    readonly kind: 'replied';
+    readonly sessionState: UssdRepliedState;
+}
+/** A `Cancel` was confirmed by the modem. */
+ | {
+    readonly kind: 'cancelled';
+}
+/** The network released the session without our asking (notification path). */
+ | {
+    readonly kind: 'network-released';
+}
+/** The bounded wait elapsed with no answer. */
+ | {
+    readonly kind: 'timeout';
+}
+/** The call failed. The reason is carried onto the terminal state verbatim. */
+ | {
+    readonly kind: 'failed';
+    readonly reason: UssdRefusalReason;
+};
+export interface UssdSessionSnapshot {
+    readonly state: UssdSessionState;
+    /** Present only at `closed`. */
+    readonly outcome?: UssdSessionOutcome;
+    /** Present only at `closed` with outcome `failed`. */
+    readonly refusal?: UssdRefusalReason;
+}
+export type UssdTransition = {
+    readonly ok: true;
+    readonly snapshot: UssdSessionSnapshot;
+}
+/** The verb is not legal in this state, and the machine did NOT move. */
+ | {
+    readonly ok: false;
+    readonly refusal: UssdRefusalReason;
+};
+export declare const IDLE_SESSION: UssdSessionSnapshot;
+/**
+ * Apply one event. TOTAL: every (state, event) pair has an answer, and an answer
+ * is either a new snapshot or a typed refusal that leaves the machine untouched.
+ *
+ * A `closed` machine accepts NOTHING — not even another `cancel`. Re-opening a
+ * terminal session would hide the fact that the previous one ended, and the
+ * cost of a fresh machine is one object.
+ */
+export declare function reduceUssdSession(snapshot: UssdSessionSnapshot, event: UssdSessionEvent): UssdTransition;
+/** True while the session still holds a network dialogue open. */
+export declare function isUssdSessionOpen(snapshot: UssdSessionSnapshot): boolean;