@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/backend/observer.js

@@ -0,0 +1,219 @@
+// The epoch-scoped ModemManager observer.
+//
+// `MmDbusObserver` implements the read-only `ModemObservationPort` over the A2.4
+// transport, tested against the A2.3 fake. `start()` connects, subscribes to the four
+// lifecycle signals, THEN takes the first authoritative `GetManagedObjects` snapshot —
+// reconciling any signal that raced in between.
+//
+// SAFETY-CRITICAL — epoch-scoped removal (draft §Oracle round-3 #5). An "epoch" is one
+// continuous ownership period of the MM bus name, tracked via `NameOwnerChanged`. A
+// modem is REMOVED only when it is missing from a CURRENT-epoch authoritative snapshot.
+// Owner loss, bus disconnect, and any signal whose `sender` is not the current owner
+// (an OLD-epoch straggler) never remove a modem — they only ever mark it
+// `sourceUnavailable`. The false-removal class is dead by construction: even the
+// `ObservationList` failure arm retains its rows. Row bookkeeping lives in
+// `ObservationRowStore`; this file owns epoch tracking, subscriptions, and refresh.
+import { DBUS_DESTINATION, DBUS_IFACE, DBUS_PATH, MM_BUS_NAME, MM_ROOT_PATH, OBJECT_MANAGER_IFACE, PROPERTIES_IFACE, } from './constants.js';
+import { asManagedObjects } from './managed-objects.js';
+import { ObservationRowStore } from './row-store.js';
+export class MmDbusObserver {
+    #transport;
+    #destination;
+    #onEpochRefresh;
+    #store = new ObservationRowStore();
+    #listeners = new Set();
+    #subscriptions = [];
+    #currentOwner;
+    #started = false;
+    #stopped = false;
+    #priming = false;
+    #refreshDuringPrime = false;
+    #refreshing = false;
+    #refreshQueued = false;
+    #onDisconnected = () => this.#handleSourceGone('source-unavailable');
+    #onReconnected = () => {
+        void this.#adoptCurrentOwner();
+    };
+    constructor(options) {
+        this.#transport = options.transport;
+        this.#destination = options.destination ?? MM_BUS_NAME;
+        this.#onEpochRefresh = options.onEpochRefresh;
+    }
+    async start() {
+        if (this.#started) {
+            return this.#store.list();
+        }
+        this.#started = true;
+        this.#priming = true;
+        await this.#transport.connect();
+        this.#transport.on('disconnected', this.#onDisconnected);
+        this.#transport.on('reconnected', this.#onReconnected);
+        await this.#subscribeAll();
+        await this.#adoptCurrentOwner();
+        this.#priming = false;
+        if (this.#refreshDuringPrime) {
+            this.#refreshDuringPrime = false;
+            this.#scheduleRefresh();
+        }
+        return this.#store.list();
+    }
+    observe(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    async stop() {
+        if (this.#stopped) {
+            return;
+        }
+        this.#stopped = true;
+        this.#transport.off('disconnected', this.#onDisconnected);
+        this.#transport.off('reconnected', this.#onReconnected);
+        const subs = this.#subscriptions.splice(0);
+        await Promise.all(subs.map((sub) => sub.unsubscribe().catch(() => undefined)));
+        this.#listeners.clear();
+    }
+    // ── signal subscription ────────────────────────────────────────────────────────
+    async #subscribeAll() {
+        const om = { interface: OBJECT_MANAGER_IFACE, path: MM_ROOT_PATH };
+        this.#subscriptions.push(await this.#transport.subscribeSignal({ ...om, member: 'InterfacesAdded' }, (event) => this.#onObjectSignal(event)), await this.#transport.subscribeSignal({ ...om, member: 'InterfacesRemoved' }, (event) => this.#onObjectSignal(event)), await this.#transport.subscribeSignal({ interface: PROPERTIES_IFACE, member: 'PropertiesChanged' }, (event) => this.#onObjectSignal(event)), await this.#transport.subscribeSignal({ interface: DBUS_IFACE, member: 'NameOwnerChanged' }, (event) => this.#onNameOwnerChanged(event)));
+    }
+    // ── epoch tracking ───────────────────────────────────────────────────────────
+    async #adoptCurrentOwner() {
+        const owner = await this.#queryOwner();
+        if (owner === undefined) {
+            this.#handleSourceGone('source-unavailable');
+            return;
+        }
+        this.#currentOwner = owner;
+        await this.#runRefresh(owner);
+    }
+    async #queryOwner() {
+        try {
+            const reply = await this.#transport.callMethod({
+                destination: DBUS_DESTINATION,
+                path: DBUS_PATH,
+                interface: DBUS_IFACE,
+                member: 'GetNameOwner',
+                signature: 's',
+                args: [MM_BUS_NAME],
+            });
+            const owner = reply.body[0];
+            return typeof owner === 'string' && owner.length > 0 ? owner : undefined;
+        }
+        catch {
+            // NameHasNoOwner (or a transient failure) → no current epoch yet.
+            return undefined;
+        }
+    }
+    #onNameOwnerChanged(event) {
+        if (event.body[0] !== MM_BUS_NAME) {
+            return;
+        }
+        const newOwner = typeof event.body[2] === 'string' ? event.body[2] : '';
+        if (newOwner.length === 0) {
+            // Owner lost — stale, never a removal.
+            this.#handleSourceGone('source-unavailable');
+            return;
+        }
+        if (newOwner === this.#currentOwner) {
+            return;
+        }
+        // New epoch: everything goes stale until the fresh snapshot restores it.
+        if (this.#store.markUnavailable('source-unavailable')) {
+            this.#emit();
+        }
+        this.#currentOwner = newOwner;
+        this.#scheduleRefresh();
+    }
+    #onObjectSignal(event) {
+        // Epoch guard: a signal from anyone but the current owner is an OLD-epoch
+        // straggler and must never drive a removal (draft §Oracle round-3 #5).
+        if (this.#currentOwner === undefined || event.sender !== this.#currentOwner) {
+            return;
+        }
+        if (this.#priming) {
+            this.#refreshDuringPrime = true;
+            return;
+        }
+        this.#scheduleRefresh();
+    }
+    // ── authoritative refresh ──────────────────────────────────────────────────────
+    #scheduleRefresh() {
+        const owner = this.#currentOwner;
+        if (owner === undefined || this.#stopped) {
+            return;
+        }
+        if (this.#refreshing) {
+            this.#refreshQueued = true;
+            return;
+        }
+        void this.#runRefresh(owner);
+    }
+    async #runRefresh(epochOwner) {
+        this.#refreshing = true;
+        try {
+            const reply = await this.#transport.callMethod({
+                destination: this.#destination,
+                path: MM_ROOT_PATH,
+                interface: OBJECT_MANAGER_IFACE,
+                member: 'GetManagedObjects',
+            });
+            // Late reply from a superseded epoch — discard (draft §Oracle round-3 #5).
+            if (this.#currentOwner !== epochOwner || this.#stopped) {
+                return;
+            }
+            const tree = asManagedObjects(reply.body[0]);
+            const rowsChanged = this.#store.reconcile(tree);
+            const healthChanged = this.#store.markHealthy();
+            this.#notifyEpochRefresh(epochOwner, tree);
+            if (rowsChanged || healthChanged) {
+                this.#emit();
+            }
+        }
+        catch {
+            if (this.#currentOwner === epochOwner && !this.#stopped) {
+                this.#markUnavailable('bus-error');
+            }
+        }
+        finally {
+            this.#refreshing = false;
+            if (this.#refreshQueued && !this.#stopped) {
+                this.#refreshQueued = false;
+                this.#scheduleRefresh();
+            }
+        }
+    }
+    // ── source-unavailable transitions ─────────────────────────────────────────────
+    #handleSourceGone(reason) {
+        this.#currentOwner = undefined;
+        this.#markUnavailable(reason);
+    }
+    #markUnavailable(reason) {
+        if (this.#store.markUnavailable(reason)) {
+            this.#emit();
+        }
+    }
+    #notifyEpochRefresh(epoch, tree) {
+        if (this.#onEpochRefresh === undefined) {
+            return;
+        }
+        try {
+            this.#onEpochRefresh({ epoch, tree });
+        }
+        catch {
+            // A consumer's hook must never break the observer's refresh loop.
+        }
+    }
+    #emit() {
+        const list = this.#store.list();
+        for (const listener of [...this.#listeners]) {
+            listener(list);
+        }
+    }
+}
+/** Construct an epoch-scoped ModemManager observer over an A2.4 transport. */
+export function createMmDbusObserver(options) {
+    return new MmDbusObserver(options);
+}

package/dist/backend/power-contract.d.ts

@@ -0,0 +1,49 @@
+import type { EpochMillis } from '../domain/index.js';
+/** How a board can power-cycle a modem. Only `none` is implemented in Phase A. */
+export type PowerCapabilityKind = 'none' | 'gpio-cut' | 'pwrkey-pulse' | 'usb-hub-port-cycle';
+/**
+ * The USB data mode a modem should re-enumerate into after a power cycle. A4.2 owns
+ * the certified USB-mode catalog; the power contract only records the operator's
+ * preferred post-cycle enumeration mode.
+ */
+export type PreferredUsbMode = 'qmi' | 'mbim' | 'ecm-ncm' | 'rndis' | 'router-ethernet';
+/** A board's modem power-control capability description. */
+export interface PowerCapability {
+    readonly power: PowerCapabilityKind;
+    /** The board can pulse a USB-level reset on the modem's port. */
+    readonly usbReset?: boolean;
+    /** How long to wait for the modem to re-enumerate after a cycle. */
+    readonly enumerationTimeoutMs: number;
+    /** Which USB mode to prefer when the modem re-enumerates (A4.2 catalog vocabulary). */
+    readonly preferredUsbMode?: PreferredUsbMode;
+}
+/** The Phase-A capability: no board power control exists — a no-op. */
+export declare const NONE_POWER_CAPABILITY: PowerCapability;
+/** Outcome of asking the power hook to cycle a modem. */
+export interface PowerCycleResult {
+    readonly status: 'applied' | 'unsupported' | 'failed';
+    readonly reason: string;
+}
+/** The minimal context handed to the power hook. */
+export interface PowerCycleContext {
+    readonly stableKey: string;
+    readonly at: EpochMillis;
+}
+/**
+ * The pluggable power-cycle hook (recovery ladder rung 4). Phase A ships only the
+ * `none` no-op; a real GPIO / PWRKEY / USB-hub implementation is hardware-gated and
+ * injected later without changing the ladder.
+ */
+export interface PowerHook {
+    readonly capability: PowerCapability;
+    cycle(context: PowerCycleContext): Promise<PowerCycleResult>;
+}
+/**
+ * Build a Phase-A power hook for `capability`. EVERY capability returns
+ * `unsupported`: `none` because there is nothing to cut, and every real mechanism
+ * because its hardware driver is not implemented yet — the contract field exists so
+ * a board can DECLARE the capability, but rung 4 never actuates in Phase A.
+ */
+export declare function unsupportedPowerHook(capability: PowerCapability): PowerHook;
+/** The Phase-A default power hook: describes `none` and always returns `unsupported`. */
+export declare const NONE_POWER_HOOK: PowerHook;

package/dist/backend/power-contract.js

@@ -0,0 +1,34 @@
+// The modem power-control capability contract — recovery ladder rung 4.
+//
+// Power control becomes a first-class v1 CONTRACT (draft §gap sweep: Sixfab GPIO26
+// power-cut + PWRKEY-pulse boards, BELABOX-reported RM520N USB instability needing a
+// powered carrier). The FIELDS ship in Phase A; the board-specific GPIO / USB-hub
+// IMPLEMENTATIONS stay hardware-gated. Only the `none` capability is implemented (a
+// no-op), so ladder rung 4 always returns `unsupported` on today's hardware — every
+// real mechanism is a typed-but-unsupported placeholder.
+/** The Phase-A capability: no board power control exists — a no-op. */
+export const NONE_POWER_CAPABILITY = {
+    power: 'none',
+    enumerationTimeoutMs: 30_000,
+};
+/**
+ * Build a Phase-A power hook for `capability`. EVERY capability returns
+ * `unsupported`: `none` because there is nothing to cut, and every real mechanism
+ * because its hardware driver is not implemented yet — the contract field exists so
+ * a board can DECLARE the capability, but rung 4 never actuates in Phase A.
+ */
+export function unsupportedPowerHook(capability) {
+    return {
+        capability,
+        cycle() {
+            return Promise.resolve({
+                status: 'unsupported',
+                reason: capability.power === 'none'
+                    ? "power capability 'none' — no board power control exists"
+                    : `power capability '${capability.power}' is declared but not implemented in Phase A`,
+            });
+        },
+    };
+}
+/** The Phase-A default power hook: describes `none` and always returns `unsupported`. */
+export const NONE_POWER_HOOK = unsupportedPowerHook(NONE_POWER_CAPABILITY);

package/dist/backend/recovery-attribution.d.ts

@@ -0,0 +1,32 @@
+import type { CellularSnapshot, MmState, NmActivation, Presence, RegistrationStatus, SourceHealth } from '../domain/index.js';
+/**
+ * The confident classification of a modem fault:
+ *   - `modem-fault`    — the modem itself is broken (only this may be disruptive).
+ *   - `network-fault`  — attached to (or refused by) the network; the modem is fine.
+ *   - `indeterminate`  — ambiguous, or observed from an unreliable source.
+ */
+export type FaultAttribution = 'modem-fault' | 'network-fault' | 'indeterminate';
+/** The narrow set of symptoms attribution reasons over. */
+export interface FaultSymptoms {
+    readonly sourceHealth: SourceHealth;
+    readonly presence: Presence;
+    readonly mmState: MmState;
+    readonly registration: RegistrationStatus;
+    readonly nmActivation: NmActivation;
+}
+/**
+ * Classify a modem fault from observed symptoms.
+ *
+ * HARD SAFETY INVARIANT (draft §round-5 stale-forces-indeterminate): if the
+ * observation SOURCE is not `live` — i.e. `stale` or `sourceUnavailable`, as A3.1's
+ * epoch observer reports on owner loss / bus disconnect / old-epoch signals — the
+ * attribution is FORCED to `indeterminate`. We never guess `modem-fault` or
+ * `network-fault` from unreliable data. Because only a confident `modem-fault` can
+ * later authorise a disruptive step, forcing indeterminate here makes stale input
+ * strictly safe: no ladder step can fire off data we do not trust.
+ */
+export declare function attributeFault(symptoms: FaultSymptoms): FaultAttribution;
+/** Project the symptoms attribution needs out of a full snapshot. */
+export declare function symptomsFromSnapshot(snapshot: CellularSnapshot): FaultSymptoms;
+/** Attribute a fault directly from a snapshot (symptoms projection + classify). */
+export declare function attributeSnapshot(snapshot: CellularSnapshot): FaultAttribution;

package/dist/backend/recovery-attribution.js

@@ -0,0 +1,57 @@
+// Fault attribution — the safety gate the recovery ladder is built around.
+//
+// Before any disruptive recovery action, a fault MUST be attributed. Recovery may
+// ONLY ever act on a confident `modem-fault`; `network-fault` and `indeterminate`
+// never authorise a disruptive step (draft §Oracle recovery: "fault attribution
+// required before disruptive action"). This module is pure — it classifies from a
+// narrow projection of one snapshot and never performs I/O.
+import { isRegistered } from '../domain/index.js';
+/**
+ * Classify a modem fault from observed symptoms.
+ *
+ * HARD SAFETY INVARIANT (draft §round-5 stale-forces-indeterminate): if the
+ * observation SOURCE is not `live` — i.e. `stale` or `sourceUnavailable`, as A3.1's
+ * epoch observer reports on owner loss / bus disconnect / old-epoch signals — the
+ * attribution is FORCED to `indeterminate`. We never guess `modem-fault` or
+ * `network-fault` from unreliable data. Because only a confident `modem-fault` can
+ * later authorise a disruptive step, forcing indeterminate here makes stale input
+ * strictly safe: no ladder step can fire off data we do not trust.
+ */
+export function attributeFault(symptoms) {
+    // 1. Unreliable source → never guess. (The invariant — checked first.)
+    if (symptoms.sourceHealth !== 'live') {
+        return 'indeterminate';
+    }
+    // 2. Nothing present to attribute (and nothing to act on via D-Bus).
+    if (symptoms.presence === 'absent') {
+        return 'indeterminate';
+    }
+    // 3. MM — a healthy source — reports THIS modem terminally failed → modem-fault.
+    if (symptoms.mmState === 'failed') {
+        return 'modem-fault';
+    }
+    // 4. The network refused registration → network-fault (not the modem's fault).
+    if (symptoms.registration === 'denied') {
+        return 'network-fault';
+    }
+    // 5. Registered to a network but data is not up → registered-but-no-data.
+    if (isRegistered(symptoms.registration) && symptoms.nmActivation !== 'activated') {
+        return 'network-fault';
+    }
+    // 6. Anything else is ambiguous — stay safe.
+    return 'indeterminate';
+}
+/** Project the symptoms attribution needs out of a full snapshot. */
+export function symptomsFromSnapshot(snapshot) {
+    return {
+        sourceHealth: snapshot.sourceHealth,
+        presence: snapshot.presence,
+        mmState: snapshot.mmState,
+        registration: snapshot.registration.status,
+        nmActivation: snapshot.nmActivation,
+    };
+}
+/** Attribute a fault directly from a snapshot (symptoms projection + classify). */
+export function attributeSnapshot(snapshot) {
+    return attributeFault(symptomsFromSnapshot(snapshot));
+}

package/dist/backend/recovery-budget.d.ts

@@ -0,0 +1,45 @@
+import type { EpochMillis } from '../domain/index.js';
+/**
+ * Recovery budget. `maxAttempts` recovery attempts are allowed before the loop-stop
+ * engages; two attempts sooner than `cooldownMs` apart are refused (cooldown).
+ */
+export interface RecoveryBudget {
+    readonly maxAttempts: number;
+    readonly cooldownMs: number;
+}
+/** The Phase-A default: two attempts, 30s cooldown between them. */
+export declare const DEFAULT_RECOVERY_BUDGET: RecoveryBudget;
+/**
+ * Per-modem budget bookkeeping. `degraded` is a LATCH: once the loop-stop fires it
+ * stays set until an explicit `markRecovered`, so a flapping modem is left degraded
+ * rather than retried forever.
+ */
+export interface RecoveryBudgetState {
+    readonly attempts: number;
+    readonly degraded: boolean;
+    readonly lastAttemptAt?: EpochMillis;
+}
+/** A fresh, un-attempted budget state. */
+export declare const INITIAL_BUDGET_STATE: RecoveryBudgetState;
+/** The verdict on whether a recovery attempt may proceed, plus the next state. */
+export type BudgetDecision = {
+    readonly kind: 'proceed';
+    readonly state: RecoveryBudgetState;
+} | {
+    readonly kind: 'cooldown';
+    readonly state: RecoveryBudgetState;
+    readonly retryAfter: EpochMillis;
+} | {
+    readonly kind: 'loop-stop';
+    readonly state: RecoveryBudgetState;
+};
+/**
+ * Decide whether a recovery attempt may proceed at `now`, returning the NEXT state:
+ *   - already `degraded`            → loop-stop (latched; zero further attempts)
+ *   - within `cooldownMs` of last   → cooldown  (refused; attempts NOT incremented)
+ *   - budget already spent          → loop-stop (latch `degraded`)
+ *   - otherwise                     → proceed   (attempts + 1; stamp `lastAttemptAt`)
+ */
+export declare function beginAttempt(state: RecoveryBudgetState, budget: RecoveryBudget, now: EpochMillis): BudgetDecision;
+/** A successful recovery clears the counter and the degraded latch. */
+export declare function markRecovered(): RecoveryBudgetState;

package/dist/backend/recovery-budget.js

@@ -0,0 +1,44 @@
+// Recovery budget — the bounded-attempts / cooldown / loop-stop circuit breaker.
+//
+// A permanently-broken modem must not be recovered forever. The budget caps how many
+// attempts may fire within a cooldown window; once the cap is spent it latches the
+// modem `degraded` (the loop-stop), and no further attempt is allowed until an
+// explicit reset. This module is a PURE reducer: it owns no clock and mutates
+// nothing — the caller supplies `now` and stores the returned next state.
+/** The Phase-A default: two attempts, 30s cooldown between them. */
+export const DEFAULT_RECOVERY_BUDGET = {
+    maxAttempts: 2,
+    cooldownMs: 30_000,
+};
+/** A fresh, un-attempted budget state. */
+export const INITIAL_BUDGET_STATE = {
+    attempts: 0,
+    degraded: false,
+};
+/**
+ * Decide whether a recovery attempt may proceed at `now`, returning the NEXT state:
+ *   - already `degraded`            → loop-stop (latched; zero further attempts)
+ *   - within `cooldownMs` of last   → cooldown  (refused; attempts NOT incremented)
+ *   - budget already spent          → loop-stop (latch `degraded`)
+ *   - otherwise                     → proceed   (attempts + 1; stamp `lastAttemptAt`)
+ */
+export function beginAttempt(state, budget, now) {
+    if (state.degraded) {
+        return { kind: 'loop-stop', state };
+    }
+    if (state.lastAttemptAt !== undefined && now - state.lastAttemptAt < budget.cooldownMs) {
+        const retryAfter = (state.lastAttemptAt + budget.cooldownMs);
+        return { kind: 'cooldown', state, retryAfter };
+    }
+    if (state.attempts >= budget.maxAttempts) {
+        return { kind: 'loop-stop', state: { ...state, degraded: true } };
+    }
+    return {
+        kind: 'proceed',
+        state: { attempts: state.attempts + 1, degraded: false, lastAttemptAt: now },
+    };
+}
+/** A successful recovery clears the counter and the degraded latch. */
+export function markRecovered() {
+    return INITIAL_BUDGET_STATE;
+}

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

@@ -0,0 +1,94 @@
+import type { DesiredRecovery, EpochMillis } from '../domain/index.js';
+import type { ModemRef } from '../ports/index.js';
+import { type LifecycleInterlock } from './lifecycle-interlock.js';
+import type { ModemActor } from './modem-actor.js';
+import { type PowerHook } from './power-contract.js';
+import type { FaultAttribution } from './recovery-attribution.js';
+import { type RecoveryBudget, type RecoveryBudgetState } from './recovery-budget.js';
+export declare const LADDER_ORDER: readonly ['nmCycle', 'mmCycle', 'reset', 'powerCycle'];
+export type RecoveryRung = (typeof LADDER_ORDER)[number];
+/** Context handed to each disruptive rung. */
+export interface RecoveryStepContext {
+    readonly stableKey: string;
+    readonly modem: ModemRef;
+    readonly at: EpochMillis;
+}
+/** Outcome of a disruptive rung (1–3). */
+export interface StepOutcome {
+    readonly status: 'applied' | 'failed';
+    readonly reason: string;
+}
+/**
+ * The disruptive recovery actions for rungs 1–3. Each is the raw effect only — the
+ * ladder wraps every call in `actor.run(stableKey, …)`, so serialisation is the
+ * ladder's job, not the step's. Phase A injects a fake in tests; the real D-Bus / NM
+ * implementation (hardware-gated) is wired at the composition root.
+ */
+export interface RecoverySteps {
+    /** Rung 1: NM deactivate then reactivate — an EXACT pair, never a bare deactivate. */
+    nmCycle(context: RecoveryStepContext): Promise<StepOutcome>;
+    /** Rung 2: MM disable then enable. */
+    mmCycle(context: RecoveryStepContext): Promise<StepOutcome>;
+    /** Rung 3: MM `Reset()`. */
+    reset(context: RecoveryStepContext): Promise<StepOutcome>;
+}
+export interface RecoveryStepGate {
+    readonly allowDisruptive: boolean;
+}
+/** The ladder's operational config: per-rung gates + the attempt budget. */
+export interface RecoveryLadderConfig {
+    readonly nmCycle: RecoveryStepGate;
+    readonly mmCycle: RecoveryStepGate;
+    readonly reset: RecoveryStepGate;
+    readonly powerCycle: RecoveryStepGate;
+    readonly budget: RecoveryBudget;
+}
+/** Default config: every rung permitted, default budget. */
+export declare const DEFAULT_LADDER_CONFIG: RecoveryLadderConfig;
+export interface RecoveryStepReport {
+    readonly rung: RecoveryRung;
+    readonly status: 'applied' | 'unsupported' | 'failed' | 'skipped' | 'blocked';
+    readonly reason: string;
+}
+/** How a whole ladder invocation ended. */
+export type RecoveryOutcomeKind = 'disabled' | 'not-attributed' | 'cooldown' | 'loop-stop' | 'interlock-blocked' | 'recovered' | 'exhausted';
+/** The result of one ladder invocation. */
+export interface RecoveryOutcome {
+    readonly kind: RecoveryOutcomeKind;
+    readonly attribution: FaultAttribution;
+    readonly steps: readonly RecoveryStepReport[];
+    readonly degraded: boolean;
+    readonly reason: string;
+}
+/** One recovery request for one modem at one instant. */
+export interface RecoveryRequest {
+    readonly stableKey: string;
+    readonly modem: ModemRef;
+    /** The pre-computed attribution (see `attributeFault`). */
+    readonly attribution: FaultAttribution;
+    readonly now: EpochMillis;
+    /** Re-checked AFTER an applied rung; `true` ⇒ the modem recovered (ladder stops). */
+    readonly probeHealthy: () => Promise<boolean>;
+}
+/** Dependencies the ladder is constructed with. */
+export interface RecoveryLadderDeps {
+    readonly actor: ModemActor;
+    readonly steps: RecoverySteps;
+    readonly powerHook?: PowerHook;
+    readonly interlock?: LifecycleInterlock;
+    readonly config?: RecoveryLadderConfig;
+}
+/**
+ * The recovery ladder. Holds per-modem budget state keyed by stable key so the
+ * loop-stop can latch a flapping modem `degraded` across invocations.
+ */
+export declare class RecoveryLadder {
+    #private;
+    constructor(deps: RecoveryLadderDeps);
+    /** The current budget state for a modem (for observability / assertions). */
+    budgetStateFor(stableKey: string): RecoveryBudgetState;
+    /** Clear a modem's budget / degraded latch (operator un-degrade). */
+    clear(stableKey: string): void;
+    /** Run one recovery attempt. Enforces every gate before any side effect. */
+    run(recovery: DesiredRecovery, request: RecoveryRequest): Promise<RecoveryOutcome>;
+}