@ceralive/modem-control 0.2.0 → 1.1.0

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

package/dist/backend/recovery-ladder.js

@@ -0,0 +1,116 @@
+// The evidence-gated recovery ladder — disabled by default.
+//
+// A bounded four-rung ladder [1 nm-cycle: NM deactivate→reactivate exact pair; 2
+// mm-cycle: MM disable→enable; 3 reset: MM Reset(); 4 power-cycle: power hook (only
+// `none` → always unsupported)]. Every disruptive rung routes through A3.3's shared
+// per-modem `ModemActor` (serialised behind all other disruptive ops) and consults
+// the `LifecycleInterlock` first so it never disrupts a streaming modem. GATES, in
+// order: recovery.enabled=false → zero steps · attribution≠modem-fault → zero steps ·
+// budget spent / cooldown → zero steps · per-rung allowDisruptive · interlock.
+// Disabled or un-attributed, NOT ONE side-effecting call is made.
+import { ALLOW_ALL_INTERLOCK } from './lifecycle-interlock.js';
+import { NONE_POWER_HOOK } from './power-contract.js';
+import { beginAttempt, DEFAULT_RECOVERY_BUDGET, INITIAL_BUDGET_STATE, markRecovered, } from './recovery-budget.js';
+export const LADDER_ORDER = ['nmCycle', 'mmCycle', 'reset', 'powerCycle'];
+const ALLOW = { allowDisruptive: true };
+/** Default config: every rung permitted, default budget. */
+export const DEFAULT_LADDER_CONFIG = {
+    nmCycle: ALLOW,
+    mmCycle: ALLOW,
+    reset: ALLOW,
+    powerCycle: ALLOW,
+    budget: DEFAULT_RECOVERY_BUDGET,
+};
+/**
+ * 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 class RecoveryLadder {
+    #actor;
+    #steps;
+    #powerHook;
+    #interlock;
+    #config;
+    #states = new Map();
+    constructor(deps) {
+        this.#actor = deps.actor;
+        this.#steps = deps.steps;
+        this.#powerHook = deps.powerHook ?? NONE_POWER_HOOK;
+        this.#interlock = deps.interlock ?? ALLOW_ALL_INTERLOCK;
+        this.#config = deps.config ?? DEFAULT_LADDER_CONFIG;
+    }
+    /** The current budget state for a modem (for observability / assertions). */
+    budgetStateFor(stableKey) {
+        return this.#states.get(stableKey) ?? INITIAL_BUDGET_STATE;
+    }
+    /** Clear a modem's budget / degraded latch (operator un-degrade). */
+    clear(stableKey) {
+        this.#states.delete(stableKey);
+    }
+    /** Run one recovery attempt. Enforces every gate before any side effect. */
+    async run(recovery, request) {
+        const { stableKey, attribution } = request;
+        // GATE 1 — master switch. Disabled ⇒ literally zero steps, zero side effects.
+        if (!recovery.enabled) {
+            return this.#end('disabled', request, [], 'recovery disabled by policy');
+        }
+        // GATE 2 — attribution. Only a confident modem-fault may ever be disruptive.
+        if (attribution !== 'modem-fault') {
+            return this.#end('not-attributed', request, [], `attribution '${attribution}' is never disruptive`);
+        }
+        // GATE 3 — budget / cooldown / loop-stop.
+        const decision = beginAttempt(this.budgetStateFor(stableKey), this.#config.budget, request.now);
+        if (decision.kind === 'loop-stop') {
+            this.#states.set(stableKey, decision.state);
+            return this.#end('loop-stop', request, [], 'recovery budget exhausted — modem marked degraded');
+        }
+        if (decision.kind === 'cooldown') {
+            return this.#end('cooldown', request, [], 'within cooldown window — attempt refused');
+        }
+        this.#states.set(stableKey, decision.state);
+        return this.#runRungs(request);
+    }
+    async #runRungs(request) {
+        const { stableKey } = request;
+        const context = { stableKey, modem: request.modem, at: request.now };
+        const steps = [];
+        for (const rung of LADDER_ORDER) {
+            if (!this.#config[rung].allowDisruptive) {
+                steps.push({ rung, status: 'skipped', reason: 'allowDisruptive is false' });
+                continue;
+            }
+            // Interlock BEFORE any disruptive step — never disrupt a streaming modem.
+            const verdict = await this.#interlock.canDisrupt({ stableKey });
+            if (!verdict.allow) {
+                steps.push({ rung, status: 'blocked', reason: verdict.reason });
+                return this.#end('interlock-blocked', request, steps, `interlock blocked '${rung}': ${verdict.reason}`);
+            }
+            const report = await this.#runRung(rung, context);
+            steps.push(report);
+            if (report.status === 'applied' && (await request.probeHealthy())) {
+                this.#states.set(stableKey, markRecovered());
+                return this.#end('recovered', request, steps, `recovered at rung '${rung}'`);
+            }
+        }
+        return this.#end('exhausted', request, steps, 'ladder exhausted without restoring health');
+    }
+    async #runRung(rung, context) {
+        if (rung === 'powerCycle') {
+            const result = await this.#powerHook.cycle({ stableKey: context.stableKey, at: context.at });
+            return { rung, status: result.status, reason: result.reason };
+        }
+        // Rungs 1–3 route through the shared per-modem actor for serialisation.
+        const step = this.#steps[rung];
+        const outcome = await this.#actor.run(context.stableKey, () => step(context));
+        return { rung, status: outcome.status, reason: outcome.reason };
+    }
+    #end(kind, request, steps, reason) {
+        return {
+            kind,
+            attribution: request.attribution,
+            steps,
+            degraded: this.budgetStateFor(request.stableKey).degraded,
+            reason,
+        };
+    }
+}

package/dist/backend/router-ethernet.d.ts

@@ -0,0 +1,19 @@
+import { type EpochMillis } from '../domain/index.js';
+import type { DeviceIfname, RouterPort } from '../ports/index.js';
+/** Injectable probes — each defaults to a `Bun.spawn` shell-out; all advisory. */
+export interface RouterEthernetProbeDeps {
+    readonly now?: () => EpochMillis;
+    /** Whether `ifname` exists and is administratively up. */
+    readonly checkLinkUp?: (ifname: DeviceIfname) => Promise<boolean>;
+    /** The DHCP-assigned default gateway on `ifname`, if any. */
+    readonly resolveGateway?: (ifname: DeviceIfname) => Promise<string | undefined>;
+    /** Whether `host` is reachable via `ifname` (ICMP). */
+    readonly ping?: (host: string, ifname: DeviceIfname) => Promise<boolean>;
+}
+/**
+ * Create a router-ethernet probe implementing the advisory `RouterPort`. Presence is
+ * link-up; health additionally reports DHCP-gateway reachability and a basic egress
+ * probe — all informational, never a gate. `checkHealth` swallows every error into a
+ * `false` field so it can never throw.
+ */
+export declare function createRouterEthernetProbe(deps?: RouterEthernetProbeDeps): RouterPort;

package/dist/backend/router-ethernet.js

@@ -0,0 +1,66 @@
+// Generic router-ethernet detection — presence, DHCP-gateway reachability, and a
+// basic egress-health probe for uplinks ModemManager cannot control (HiLink, RNDIS
+// tether, full router firmware).
+//
+// EVERYTHING here is ADVISORY (ports/router.ts, matrix §1-R): health degradation is
+// informational only. `checkHealth` NEVER throws and NEVER gates anything — a
+// degraded router stays in the routing set; the controller merely reports what it
+// observed. Each probe is an injectable seam (default `Bun.spawn` of `ip` / `ping`)
+// so tests run with no real network.
+import { epochMillis } from '../domain/index.js';
+/** The host used for the basic egress-health probe (public DNS anycast). */
+const EGRESS_PROBE_HOST = '1.1.1.1';
+async function spawnSucceeds(command) {
+    try {
+        const proc = Bun.spawn([...command], { stdout: 'pipe', stderr: 'pipe' });
+        return (await proc.exited) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function spawnOutput(command) {
+    try {
+        const proc = Bun.spawn([...command], { stdout: 'pipe', stderr: 'pipe' });
+        const [out, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+        return code === 0 ? out : '';
+    }
+    catch {
+        return '';
+    }
+}
+function defaultCheckLinkUp(ifname) {
+    return spawnSucceeds(['ip', 'link', 'show', 'up', 'dev', String(ifname)]);
+}
+async function defaultResolveGateway(ifname) {
+    // `ip -o route show default dev <ifname>` → "default via 192.168.8.1 dev <ifname> …".
+    const out = await spawnOutput(['ip', '-o', 'route', 'show', 'default', 'dev', String(ifname)]);
+    const match = out.match(/default via (\S+)/);
+    return match?.[1];
+}
+function defaultPing(host, ifname) {
+    return spawnSucceeds(['ping', '-c', '1', '-W', '2', '-I', String(ifname), host]);
+}
+/**
+ * Create a router-ethernet probe implementing the advisory `RouterPort`. Presence is
+ * link-up; health additionally reports DHCP-gateway reachability and a basic egress
+ * probe — all informational, never a gate. `checkHealth` swallows every error into a
+ * `false` field so it can never throw.
+ */
+export function createRouterEthernetProbe(deps = {}) {
+    const now = deps.now ?? (() => epochMillis(Date.now()));
+    const checkLinkUp = deps.checkLinkUp ?? defaultCheckLinkUp;
+    const resolveGateway = deps.resolveGateway ?? defaultResolveGateway;
+    const ping = deps.ping ?? defaultPing;
+    async function probePresence(ifname) {
+        return (await checkLinkUp(ifname).catch(() => false)) ? 'present' : 'absent';
+    }
+    async function checkHealth(ifname) {
+        const presence = await probePresence(ifname);
+        const gateway = presence === 'present' ? await resolveGateway(ifname).catch(() => undefined) : undefined;
+        const gatewayReachable = gateway !== undefined && (await ping(gateway, ifname).catch(() => false));
+        const egressHealthy = gatewayReachable && (await ping(EGRESS_PROBE_HOST, ifname).catch(() => false));
+        return { presence, gatewayReachable, egressHealthy, observedAt: now() };
+    }
+    return { probePresence, checkHealth };
+}

package/dist/backend/row-store.d.ts

@@ -0,0 +1,13 @@
+import type { ObservationFailureReason, ObservationList } from '../ports/index.js';
+import type { DecodedManagedObjects } from './managed-objects.js';
+export declare class ObservationRowStore {
+    #private;
+    /** Reconcile the authoritative tree into the rows. Returns whether rows changed.
+     *  This is the SOLE removal path — an omission from a current-epoch snapshot. */
+    reconcile(tree: DecodedManagedObjects): boolean;
+    /** Mark the source healthy after a successful reconcile. Returns whether health flipped. */
+    markHealthy(): boolean;
+    /** Flag every row stale (retained, never removed). Returns whether an emission is due. */
+    markUnavailable(reason: ObservationFailureReason): boolean;
+    list(): ObservationList;
+}

package/dist/backend/row-store.js

@@ -0,0 +1,82 @@
+// The observer's row bookkeeping — revisions, source health, and the discriminated
+// list result — split out of the observer so each file stays focused.
+//
+// Removal lives ONLY in `reconcile`: a modem is dropped exactly when a current-epoch
+// authoritative snapshot omits it. `markUnavailable` never removes — it flags rows
+// stale and retains them, so the `ObservationList` failure arm always carries its rows.
+import { createSnapshot, revision as makeRevision, markSourceUnavailable, } from '../domain/index.js';
+import { fingerprint, mapModem, modemPaths } from './mapping.js';
+export class ObservationRowStore {
+    #rows = new Map();
+    #revCounter = 0;
+    #sourceHealthy = false;
+    #failureReason = 'not-started';
+    /** Reconcile the authoritative tree into the rows. Returns whether rows changed.
+     *  This is the SOLE removal path — an omission from a current-epoch snapshot. */
+    reconcile(tree) {
+        let changed = false;
+        const seen = new Set();
+        for (const path of modemPaths(tree)) {
+            seen.add(path);
+            if (this.#upsert(path, mapModem(tree, path))) {
+                changed = true;
+            }
+        }
+        for (const path of [...this.#rows.keys()]) {
+            if (!seen.has(path)) {
+                this.#rows.delete(path);
+                changed = true;
+            }
+        }
+        return changed;
+    }
+    /** Mark the source healthy after a successful reconcile. Returns whether health flipped. */
+    markHealthy() {
+        const flipped = !this.#sourceHealthy;
+        this.#sourceHealthy = true;
+        return flipped;
+    }
+    /** Flag every row stale (retained, never removed). Returns whether an emission is due. */
+    markUnavailable(reason) {
+        const wasHealthy = this.#sourceHealthy;
+        let changed = false;
+        for (const [path, row] of this.#rows) {
+            if (row.snapshot.sourceHealth === 'sourceUnavailable') {
+                continue;
+            }
+            this.#rows.set(path, {
+                snapshot: markSourceUnavailable(row.snapshot),
+                fingerprint: row.fingerprint,
+            });
+            changed = true;
+        }
+        this.#sourceHealthy = false;
+        this.#failureReason = reason;
+        return changed || wasHealthy;
+    }
+    list() {
+        const rows = [...this.#rows.values()].map((row) => row.snapshot);
+        if (this.#sourceHealthy) {
+            return { ok: true, rows };
+        }
+        return { ok: false, reason: this.#failureReason, rows };
+    }
+    #upsert(path, mapped) {
+        const fp = fingerprint(mapped);
+        const existing = this.#rows.get(path);
+        if (existing !== undefined &&
+            existing.fingerprint === fp &&
+            existing.snapshot.sourceHealth === 'live') {
+            return false;
+        }
+        this.#rows.set(path, {
+            snapshot: createSnapshot({ ...mapped, revision: this.#nextRevision() }),
+            fingerprint: fp,
+        });
+        return true;
+    }
+    #nextRevision() {
+        this.#revCounter += 1;
+        return makeRevision(this.#revCounter);
+    }
+}

package/dist/backend/signal-setup.d.ts

@@ -0,0 +1,30 @@
+import type { DbusTransport } from '../transport/index.js';
+import type { DecodedManagedObjects } from './managed-objects.js';
+/** Whether periodic signal reporting is configured for a modem. */
+export type SignalCadence = 'active' | 'unsupported' | 'unknown';
+/** MM's default reporting rate is seconds; callers pass whole seconds. */
+export declare const DEFAULT_SIGNAL_INTERVAL_SECONDS = 5;
+export interface SignalSetupManagerOptions {
+    readonly transport: DbusTransport;
+    /** MM bus name override (defaults to `org.freedesktop.ModemManager1`). */
+    readonly destination?: string;
+    /** Reporting interval in seconds passed to `Signal.Setup`. */
+    readonly intervalSeconds?: number;
+}
+/**
+ * Drives `Signal.Setup` across the modem fleet, keyed to the observer's epochs. Feed
+ * it every `onEpochRefresh` event; it applies setup to each modem exactly once per
+ * epoch, re-applies to survivors on a new epoch, and never calls for an old one.
+ */
+export declare class SignalSetupManager {
+    #private;
+    constructor(options: SignalSetupManagerOptions);
+    /** The last-known cadence for a modem path (`'unknown'` until first applied). */
+    cadenceFor(modemPath: string): SignalCadence;
+    /**
+     * Apply `Signal.Setup` for the current epoch's modems. New epoch ⇒ every survivor
+     * is re-applied; an already-applied (epoch, modem) is skipped. Modems absent from
+     * this snapshot keep their last cadence but are not re-driven.
+     */
+    applyForEpoch(epoch: string, tree: DecodedManagedObjects): void;
+}