@ceralive/modem-control 0.2.0 → 1.1.0

package/src/backend/recovery-budget.ts

@@ -1,84 +0,0 @@
-// 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.
-
-import type { EpochMillis } from '../domain';
-
-/**
- * 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 const DEFAULT_RECOVERY_BUDGET: RecoveryBudget = {
-	maxAttempts: 2,
-	cooldownMs: 30_000,
-};
-
-/**
- * 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 const INITIAL_BUDGET_STATE: RecoveryBudgetState = {
-	attempts: 0,
-	degraded: false,
-};
-
-/** 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 function beginAttempt(
-	state: RecoveryBudgetState,
-	budget: RecoveryBudget,
-	now: EpochMillis,
-): BudgetDecision {
-	if (state.degraded) {
-		return { kind: 'loop-stop', state };
-	}
-	if (state.lastAttemptAt !== undefined && now - state.lastAttemptAt < budget.cooldownMs) {
-		const retryAfter = (state.lastAttemptAt + budget.cooldownMs) as EpochMillis;
-		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(): RecoveryBudgetState {
-	return INITIAL_BUDGET_STATE;
-}

package/src/backend/recovery-ladder.test.ts

@@ -1,257 +0,0 @@
-// The recovery ladder — the safety gates are the whole point:
-//   - disabled by default ⇒ literally ZERO side effects (throwing spies prove it)
-//   - only a confident modem-fault may ever be disruptive
-//   - budget → loop-stop marks a flapping modem degraded, never retried forever
-//   - a successful step restores health and resets the budget
-//   - rung 4 (power) is always unsupported in Phase A
-//   - disruptive rungs route through the shared per-modem actor (serialisation)
-
-import { describe, expect, test } from 'bun:test';
-import { type DesiredRecovery, epochMillis, runtimePath } from '../domain';
-import { ALLOW_ALL_INTERLOCK, type LifecycleInterlock } from './lifecycle-interlock';
-import { ModemActor } from './modem-actor';
-import { NONE_POWER_CAPABILITY, type PowerHook } from './power-contract';
-import { DEFAULT_RECOVERY_BUDGET } from './recovery-budget';
-import {
-	RecoveryLadder,
-	type RecoveryLadderConfig,
-	type RecoveryRequest,
-	type RecoverySteps,
-	type StepOutcome,
-} from './recovery-ladder';
-
-const ENABLED: DesiredRecovery = { enabled: true };
-const DISABLED: DesiredRecovery = { enabled: false };
-
-const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
-
-interface StepCalls {
-	nmCycle: number;
-	mmCycle: number;
-	reset: number;
-}
-
-/** Steps that count calls and return a fixed outcome. */
-function countingSteps(outcome: StepOutcome, calls: StepCalls): RecoverySteps {
-	return {
-		nmCycle: () => {
-			calls.nmCycle += 1;
-			return Promise.resolve(outcome);
-		},
-		mmCycle: () => {
-			calls.mmCycle += 1;
-			return Promise.resolve(outcome);
-		},
-		reset: () => {
-			calls.reset += 1;
-			return Promise.resolve(outcome);
-		},
-	};
-}
-
-/** Steps that throw if ever invoked — the strongest "zero side effects" proof. */
-const throwingSteps: RecoverySteps = {
-	nmCycle: () => Promise.reject(new Error('nmCycle must not fire')),
-	mmCycle: () => Promise.reject(new Error('mmCycle must not fire')),
-	reset: () => Promise.reject(new Error('reset must not fire')),
-};
-
-const throwingPowerHook: PowerHook = {
-	capability: NONE_POWER_CAPABILITY,
-	cycle: () => Promise.reject(new Error('power hook must not fire')),
-};
-
-const throwingInterlock: LifecycleInterlock = {
-	canDisrupt: () => Promise.reject(new Error('interlock must not be consulted')),
-};
-
-function makeRequest(overrides: Partial<RecoveryRequest> = {}): RecoveryRequest {
-	return {
-		stableKey: 'slot:a',
-		modem: runtimePath('/org/freedesktop/ModemManager1/Modem/0'),
-		attribution: 'modem-fault',
-		now: epochMillis(0),
-		probeHealthy: () => Promise.resolve(false),
-		...overrides,
-	};
-}
-
-describe('RecoveryLadder — disabled by default fires ZERO steps', () => {
-	test('recovery.enabled=false makes zero side-effecting calls, even for a clear modem-fault', async () => {
-		const ladder = new RecoveryLadder({
-			actor: new ModemActor(),
-			steps: throwingSteps,
-			powerHook: throwingPowerHook,
-			interlock: throwingInterlock,
-		});
-		// If ANY of the throwing spies leaked through, run() would reject here.
-		const outcome = await ladder.run(DISABLED, makeRequest({ attribution: 'modem-fault' }));
-		expect(outcome.kind).toBe('disabled');
-		expect(outcome.steps).toEqual([]);
-		expect(outcome.degraded).toBe(false);
-	});
-});
-
-describe('RecoveryLadder — attribution gating (never disrupt on non-modem-fault)', () => {
-	for (const attribution of ['indeterminate', 'network-fault'] as const) {
-		test(`enabled + '${attribution}' fires zero disruptive steps`, async () => {
-			const ladder = new RecoveryLadder({
-				actor: new ModemActor(),
-				steps: throwingSteps,
-				powerHook: throwingPowerHook,
-				interlock: throwingInterlock,
-			});
-			const outcome = await ladder.run(ENABLED, makeRequest({ attribution }));
-			expect(outcome.kind).toBe('not-attributed');
-			expect(outcome.steps).toEqual([]);
-		});
-	}
-});
-
-describe('RecoveryLadder — budget, cooldown, loop-stop', () => {
-	test('a flapping modem gets EXACTLY 2 attempts, then loop-stop marks it degraded', async () => {
-		const calls: StepCalls = { nmCycle: 0, mmCycle: 0, reset: 0 };
-		const ladder = new RecoveryLadder({
-			actor: new ModemActor(),
-			steps: countingSteps({ status: 'failed', reason: 'still broken' }, calls),
-			config: { ...allowAll(), budget: { maxAttempts: 2, cooldownMs: 1000 } },
-		});
-
-		const a1 = await ladder.run(ENABLED, makeRequest({ now: epochMillis(0) }));
-		const a2 = await ladder.run(ENABLED, makeRequest({ now: epochMillis(1000) }));
-		const a3 = await ladder.run(ENABLED, makeRequest({ now: epochMillis(2000) }));
-
-		expect(a1.kind).toBe('exhausted');
-		expect(a2.kind).toBe('exhausted');
-		expect(a3.kind).toBe('loop-stop');
-		// Rung 1 fired exactly twice — the third invocation short-circuited.
-		expect(calls.nmCycle).toBe(2);
-		expect(a3.degraded).toBe(true);
-		expect(ladder.budgetStateFor('slot:a').degraded).toBe(true);
-	});
-
-	test('a second attempt within the cooldown window is refused with zero steps', async () => {
-		const calls: StepCalls = { nmCycle: 0, mmCycle: 0, reset: 0 };
-		const ladder = new RecoveryLadder({
-			actor: new ModemActor(),
-			steps: countingSteps({ status: 'failed', reason: 'still broken' }, calls),
-			config: { ...allowAll(), budget: { maxAttempts: 3, cooldownMs: 1000 } },
-		});
-		await ladder.run(ENABLED, makeRequest({ now: epochMillis(0) }));
-		const soon = await ladder.run(ENABLED, makeRequest({ now: epochMillis(500) }));
-		expect(soon.kind).toBe('cooldown');
-		expect(calls.nmCycle).toBe(1);
-	});
-});
-
-describe('RecoveryLadder — a successful step restores health', () => {
-	test('rung 1 succeeding + a healthy probe → recovered, later rungs never run, budget reset', async () => {
-		const calls: StepCalls = { nmCycle: 0, mmCycle: 0, reset: 0 };
-		const ladder = new RecoveryLadder({
-			actor: new ModemActor(),
-			steps: countingSteps({ status: 'applied', reason: 'nm reactivated' }, calls),
-		});
-		const outcome = await ladder.run(
-			ENABLED,
-			makeRequest({ probeHealthy: () => Promise.resolve(true) }),
-		);
-		expect(outcome.kind).toBe('recovered');
-		expect(calls.nmCycle).toBe(1);
-		expect(calls.mmCycle).toBe(0);
-		expect(calls.reset).toBe(0);
-		expect(ladder.budgetStateFor('slot:a').attempts).toBe(0);
-		expect(outcome.degraded).toBe(false);
-	});
-});
-
-describe('RecoveryLadder — rung 4 (power) is always unsupported', () => {
-	test('with rungs 1-3 gated off, the power rung runs and reports unsupported', async () => {
-		const ladder = new RecoveryLadder({
-			actor: new ModemActor(),
-			// Throwing steps prove rungs 1-3 are skipped (allowDisruptive:false), not run.
-			steps: throwingSteps,
-			config: {
-				nmCycle: { allowDisruptive: false },
-				mmCycle: { allowDisruptive: false },
-				reset: { allowDisruptive: false },
-				powerCycle: { allowDisruptive: true },
-				budget: DEFAULT_RECOVERY_BUDGET,
-			},
-		});
-		const outcome = await ladder.run(ENABLED, makeRequest());
-		expect(outcome.kind).toBe('exhausted');
-		const power = outcome.steps.find((s) => s.rung === 'powerCycle');
-		expect(power?.status).toBe('unsupported');
-		expect(power?.reason).toContain('none');
-		// The gated rungs are reported skipped, never executed.
-		expect(outcome.steps.filter((s) => s.status === 'skipped').map((s) => s.rung)).toEqual([
-			'nmCycle',
-			'mmCycle',
-			'reset',
-		]);
-	});
-});
-
-describe('RecoveryLadder — interlock blocks disruption', () => {
-	test('a denying interlock stops the ladder before any step fires', async () => {
-		const calls: StepCalls = { nmCycle: 0, mmCycle: 0, reset: 0 };
-		const denying: LifecycleInterlock = {
-			canDisrupt: () => Promise.resolve({ allow: false, reason: 'modem is streaming' }),
-		};
-		const ladder = new RecoveryLadder({
-			actor: new ModemActor(),
-			steps: countingSteps({ status: 'applied', reason: 'x' }, calls),
-			interlock: denying,
-		});
-		const outcome = await ladder.run(ENABLED, makeRequest());
-		expect(outcome.kind).toBe('interlock-blocked');
-		expect(calls.nmCycle).toBe(0);
-		expect(outcome.steps[0]?.status).toBe('blocked');
-		expect(outcome.reason).toContain('streaming');
-	});
-});
-
-describe('RecoveryLadder — disruptive steps route through the shared actor', () => {
-	test('two same-key recoveries serialise their steps (no interleave)', async () => {
-		const order: string[] = [];
-		const slowSteps: RecoverySteps = {
-			nmCycle: async () => {
-				order.push('start');
-				await sleep(20);
-				order.push('end');
-				return { status: 'failed', reason: 'still broken' };
-			},
-			mmCycle: () => Promise.resolve({ status: 'failed', reason: 'x' }),
-			reset: () => Promise.resolve({ status: 'failed', reason: 'x' }),
-		};
-		const ladder = new RecoveryLadder({
-			actor: new ModemActor(),
-			// Only rung 1 is enabled so the serialisation of nmCycle is unambiguous.
-			steps: slowSteps,
-			interlock: ALLOW_ALL_INTERLOCK,
-			config: {
-				nmCycle: { allowDisruptive: true },
-				mmCycle: { allowDisruptive: false },
-				reset: { allowDisruptive: false },
-				powerCycle: { allowDisruptive: false },
-				budget: { maxAttempts: 5, cooldownMs: 0 },
-			},
-		});
-		await Promise.all([
-			ladder.run(ENABLED, makeRequest({ now: epochMillis(0) })),
-			ladder.run(ENABLED, makeRequest({ now: epochMillis(1) })),
-		]);
-		// Serialised through the actor ⇒ the first nmCycle fully completes before the second.
-		expect(order).toEqual(['start', 'end', 'start', 'end']);
-	});
-});
-
-/** Every rung allowed — the shared base for budget-focused configs. */
-function allowAll(): Omit<RecoveryLadderConfig, 'budget'> {
-	return {
-		nmCycle: { allowDisruptive: true },
-		mmCycle: { allowDisruptive: true },
-		reset: { allowDisruptive: true },
-		powerCycle: { allowDisruptive: true },
-	};
-}

package/src/backend/recovery-ladder.ts

@@ -1,249 +0,0 @@
-// 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 type { DesiredRecovery, EpochMillis } from '../domain';
-import type { ModemRef } from '../ports';
-import { ALLOW_ALL_INTERLOCK, type LifecycleInterlock } from './lifecycle-interlock';
-import type { ModemActor } from './modem-actor';
-import { NONE_POWER_HOOK, type PowerHook } from './power-contract';
-import type { FaultAttribution } from './recovery-attribution';
-import {
-	beginAttempt,
-	DEFAULT_RECOVERY_BUDGET,
-	INITIAL_BUDGET_STATE,
-	markRecovered,
-	type RecoveryBudget,
-	type RecoveryBudgetState,
-} from './recovery-budget';
-
-export const LADDER_ORDER = ['nmCycle', 'mmCycle', 'reset', 'powerCycle'] as const;
-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;
-}
-
-const ALLOW: RecoveryStepGate = { allowDisruptive: true };
-
-/** Default config: every rung permitted, default budget. */
-export const DEFAULT_LADDER_CONFIG: RecoveryLadderConfig = {
-	nmCycle: ALLOW,
-	mmCycle: ALLOW,
-	reset: ALLOW,
-	powerCycle: ALLOW,
-	budget: DEFAULT_RECOVERY_BUDGET,
-};
-
-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 class RecoveryLadder {
-	readonly #actor: ModemActor;
-	readonly #steps: RecoverySteps;
-	readonly #powerHook: PowerHook;
-	readonly #interlock: LifecycleInterlock;
-	readonly #config: RecoveryLadderConfig;
-	readonly #states = new Map<string, RecoveryBudgetState>();
-
-	constructor(deps: RecoveryLadderDeps) {
-		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: string): RecoveryBudgetState {
-		return this.#states.get(stableKey) ?? INITIAL_BUDGET_STATE;
-	}
-
-	/** Clear a modem's budget / degraded latch (operator un-degrade). */
-	clear(stableKey: string): void {
-		this.#states.delete(stableKey);
-	}
-
-	/** Run one recovery attempt. Enforces every gate before any side effect. */
-	async run(recovery: DesiredRecovery, request: RecoveryRequest): Promise<RecoveryOutcome> {
-		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: RecoveryRequest): Promise<RecoveryOutcome> {
-		const { stableKey } = request;
-		const context: RecoveryStepContext = { stableKey, modem: request.modem, at: request.now };
-		const steps: RecoveryStepReport[] = [];
-
-		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: RecoveryRung, context: RecoveryStepContext): Promise<RecoveryStepReport> {
-		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: RecoveryOutcomeKind,
-		request: RecoveryRequest,
-		steps: readonly RecoveryStepReport[],
-		reason: string,
-	): RecoveryOutcome {
-		return {
-			kind,
-			attribution: request.attribution,
-			steps,
-			degraded: this.budgetStateFor(request.stableKey).degraded,
-			reason,
-		};
-	}
-}

package/src/backend/router-ethernet.test.ts

@@ -1,71 +0,0 @@
-// The router-ethernet probe is ADVISORY: presence, gateway reachability, and egress
-// health are reported, never gated. `checkHealth` must never throw — a throwing probe
-// degrades to `false`, it does not blow up the caller.
-
-import { describe, expect, test } from 'bun:test';
-import { deviceIfname } from '../ports';
-import { createRouterEthernetProbe, type RouterEthernetProbeDeps } from './router-ethernet';
-
-const IFNAME = deviceIfname('eth1');
-
-function probeWith(overrides: RouterEthernetProbeDeps) {
-	return createRouterEthernetProbe(overrides);
-}
-
-describe('createRouterEthernetProbe — presence', () => {
-	test('a link that is up is present; a link that is down is absent', async () => {
-		const up = probeWith({ checkLinkUp: () => Promise.resolve(true) });
-		const down = probeWith({ checkLinkUp: () => Promise.resolve(false) });
-		expect(await up.probePresence(IFNAME)).toBe('present');
-		expect(await down.probePresence(IFNAME)).toBe('absent');
-	});
-});
-
-describe('createRouterEthernetProbe — advisory health', () => {
-	test('present + gateway + egress all healthy', async () => {
-		const probe = probeWith({
-			checkLinkUp: () => Promise.resolve(true),
-			resolveGateway: () => Promise.resolve('192.168.8.1'),
-			ping: () => Promise.resolve(true),
-		});
-		const health = await probe.checkHealth(IFNAME);
-		expect(health.presence).toBe('present');
-		expect(health.gatewayReachable).toBe(true);
-		expect(health.egressHealthy).toBe(true);
-	});
-
-	test('present but no gateway → degraded health, but still returned (not thrown)', async () => {
-		const probe = probeWith({
-			checkLinkUp: () => Promise.resolve(true),
-			resolveGateway: () => Promise.resolve(undefined),
-			ping: () => Promise.resolve(true),
-		});
-		const health = await probe.checkHealth(IFNAME);
-		expect(health.presence).toBe('present');
-		expect(health.gatewayReachable).toBe(false);
-		expect(health.egressHealthy).toBe(false);
-	});
-
-	test('gateway reachable but egress down → egressHealthy false only', async () => {
-		const probe = probeWith({
-			checkLinkUp: () => Promise.resolve(true),
-			resolveGateway: () => Promise.resolve('192.168.8.1'),
-			ping: (host) => Promise.resolve(host === '192.168.8.1'),
-		});
-		const health = await probe.checkHealth(IFNAME);
-		expect(health.gatewayReachable).toBe(true);
-		expect(health.egressHealthy).toBe(false);
-	});
-
-	test('checkHealth NEVER throws, even when a probe throws', async () => {
-		const probe = probeWith({
-			checkLinkUp: () => Promise.reject(new Error('ip crashed')),
-			resolveGateway: () => Promise.reject(new Error('route crashed')),
-			ping: () => Promise.reject(new Error('ping crashed')),
-		});
-		const health = await probe.checkHealth(IFNAME);
-		expect(health.presence).toBe('absent');
-		expect(health.gatewayReachable).toBe(false);
-		expect(health.egressHealthy).toBe(false);
-	});
-});