@ceralive/modem-control 0.2.0 → 1.1.0

package/src/backend/observer.ts

@@ -1,297 +0,0 @@
-// 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 type {
-	ModemObservationPort,
-	ObservationFailureReason,
-	ObservationList,
-	ObservationListener,
-	Unsubscribe,
-} from '../ports';
-import type { DbusTransport, SignalEvent, Subscription } from '../transport';
-import {
-	DBUS_DESTINATION,
-	DBUS_IFACE,
-	DBUS_PATH,
-	MM_BUS_NAME,
-	MM_ROOT_PATH,
-	OBJECT_MANAGER_IFACE,
-	PROPERTIES_IFACE,
-} from './constants';
-import { asManagedObjects, type DecodedManagedObjects } from './managed-objects';
-import { ObservationRowStore } from './row-store';
-
-/**
- * A current-epoch authoritative snapshot, delivered to `onEpochRefresh` AFTER the
- * epoch guard passes. `epoch` is the owning MM unique bus name; `tree` is the decoded
- * `GetManagedObjects` payload the snapshot was reconciled from. The Signal.Setup
- * manager (A3.3) hooks this to (re-)apply cadence per modem per epoch, and the D-Bus
- * backend uses it to refresh its path→stable-key map.
- */
-export interface EpochRefreshEvent {
-	readonly epoch: string;
-	readonly tree: DecodedManagedObjects;
-}
-
-export interface MmDbusObserverOptions {
-	/** The transport to talk D-Bus over (A2.4). The observer connects it on `start()`. */
-	readonly transport: DbusTransport;
-	/** MM bus name override (defaults to `org.freedesktop.ModemManager1`). */
-	readonly destination?: string;
-	/**
-	 * Called after EVERY successful current-epoch authoritative snapshot (start,
-	 * hot-plug, epoch change, property change) — never for a superseded epoch. The
-	 * hook fires whether or not any row changed, so a consumer always sees the live
-	 * epoch + tree. It must not throw; a throw is swallowed so it can never break the
-	 * observer's refresh loop.
-	 */
-	readonly onEpochRefresh?: (event: EpochRefreshEvent) => void;
-}
-
-export class MmDbusObserver implements ModemObservationPort {
-	readonly #transport: DbusTransport;
-	readonly #destination: string;
-	readonly #onEpochRefresh: ((event: EpochRefreshEvent) => void) | undefined;
-	readonly #store = new ObservationRowStore();
-	readonly #listeners = new Set<ObservationListener>();
-	readonly #subscriptions: Subscription[] = [];
-
-	#currentOwner: string | undefined;
-	#started = false;
-	#stopped = false;
-	#priming = false;
-	#refreshDuringPrime = false;
-	#refreshing = false;
-	#refreshQueued = false;
-
-	readonly #onDisconnected = (): void => this.#handleSourceGone('source-unavailable');
-	readonly #onReconnected = (): void => {
-		void this.#adoptCurrentOwner();
-	};
-
-	constructor(options: MmDbusObserverOptions) {
-		this.#transport = options.transport;
-		this.#destination = options.destination ?? MM_BUS_NAME;
-		this.#onEpochRefresh = options.onEpochRefresh;
-	}
-
-	async start(): Promise<ObservationList> {
-		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: ObservationListener): Unsubscribe {
-		this.#listeners.add(listener);
-		return () => {
-			this.#listeners.delete(listener);
-		};
-	}
-
-	async stop(): Promise<void> {
-		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(): Promise<void> {
-		const om = { interface: OBJECT_MANAGER_IFACE, path: MM_ROOT_PATH } as const;
-		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(): Promise<void> {
-		const owner = await this.#queryOwner();
-		if (owner === undefined) {
-			this.#handleSourceGone('source-unavailable');
-			return;
-		}
-		this.#currentOwner = owner;
-		await this.#runRefresh(owner);
-	}
-
-	async #queryOwner(): Promise<string | undefined> {
-		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: SignalEvent): void {
-		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: SignalEvent): void {
-		// 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(): void {
-		const owner = this.#currentOwner;
-		if (owner === undefined || this.#stopped) {
-			return;
-		}
-		if (this.#refreshing) {
-			this.#refreshQueued = true;
-			return;
-		}
-		void this.#runRefresh(owner);
-	}
-
-	async #runRefresh(epochOwner: string): Promise<void> {
-		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: ObservationFailureReason): void {
-		this.#currentOwner = undefined;
-		this.#markUnavailable(reason);
-	}
-
-	#markUnavailable(reason: ObservationFailureReason): void {
-		if (this.#store.markUnavailable(reason)) {
-			this.#emit();
-		}
-	}
-
-	#notifyEpochRefresh(epoch: string, tree: DecodedManagedObjects): void {
-		if (this.#onEpochRefresh === undefined) {
-			return;
-		}
-		try {
-			this.#onEpochRefresh({ epoch, tree });
-		} catch {
-			// A consumer's hook must never break the observer's refresh loop.
-		}
-	}
-
-	#emit(): void {
-		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: MmDbusObserverOptions): MmDbusObserver {
-	return new MmDbusObserver(options);
-}

package/src/backend/power-contract.test.ts

@@ -1,40 +0,0 @@
-// Power contract — only `none` is implemented, so every capability returns
-// `unsupported` in Phase A (ladder rung 4 never actuates on today's hardware).
-
-import { describe, expect, test } from 'bun:test';
-import { epochMillis } from '../domain';
-import {
-	NONE_POWER_CAPABILITY,
-	NONE_POWER_HOOK,
-	type PowerCapability,
-	unsupportedPowerHook,
-} from './power-contract';
-
-const context = { stableKey: 'slot:a', at: epochMillis(0) };
-
-describe('power contract — Phase A', () => {
-	test('the none capability describes a no-op with an enumeration timeout', () => {
-		expect(NONE_POWER_CAPABILITY.power).toBe('none');
-		expect(NONE_POWER_CAPABILITY.enumerationTimeoutMs).toBeGreaterThan(0);
-	});
-
-	test('NONE_POWER_HOOK.cycle always returns unsupported', async () => {
-		const result = await NONE_POWER_HOOK.cycle(context);
-		expect(result.status).toBe('unsupported');
-		expect(result.reason).toContain('none');
-	});
-
-	test('a real capability is typed but unsupported (declared, not implemented)', async () => {
-		const gpio: PowerCapability = {
-			power: 'gpio-cut',
-			usbReset: true,
-			enumerationTimeoutMs: 15_000,
-			preferredUsbMode: 'qmi',
-		};
-		const hook = unsupportedPowerHook(gpio);
-		expect(hook.capability.power).toBe('gpio-cut');
-		const result = await hook.cycle(context);
-		expect(result.status).toBe('unsupported');
-		expect(result.reason).toContain('gpio-cut');
-	});
-});

package/src/backend/power-contract.ts

@@ -1,83 +0,0 @@
-// 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.
-
-import type { EpochMillis } from '../domain';
-
-/** 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 const NONE_POWER_CAPABILITY: PowerCapability = {
-	power: 'none',
-	enumerationTimeoutMs: 30_000,
-};
-
-/** 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 function unsupportedPowerHook(capability: PowerCapability): PowerHook {
-	return {
-		capability,
-		cycle(): Promise<PowerCycleResult> {
-			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: PowerHook = unsupportedPowerHook(NONE_POWER_CAPABILITY);

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

@@ -1,102 +0,0 @@
-// Fault attribution — pure classification with the stale-forces-indeterminate
-// invariant as the headline safety test.
-
-import { describe, expect, test } from 'bun:test';
-import { imeiEquipmentId, initialSnapshot, type ModemIdentity, runtimePath } from '../domain';
-import {
-	attributeFault,
-	attributeSnapshot,
-	type FaultSymptoms,
-	symptomsFromSnapshot,
-} from './recovery-attribution';
-
-/** A live, present, otherwise-unremarkable symptom baseline. */
-function symptoms(overrides: Partial<FaultSymptoms> = {}): FaultSymptoms {
-	return {
-		sourceHealth: 'live',
-		presence: 'present',
-		mmState: 'connected',
-		registration: 'home',
-		nmActivation: 'activated',
-		...overrides,
-	};
-}
-
-describe('attributeFault — confident classification', () => {
-	test('MM reporting a failed modem on a live source → modem-fault', () => {
-		expect(attributeFault(symptoms({ mmState: 'failed' }))).toBe('modem-fault');
-	});
-
-	test('denied registration → network-fault', () => {
-		expect(attributeFault(symptoms({ registration: 'denied' }))).toBe('network-fault');
-	});
-
-	test('registered but NM not activated (registered-but-no-data) → network-fault', () => {
-		expect(attributeFault(symptoms({ registration: 'home', nmActivation: 'failed' }))).toBe(
-			'network-fault',
-		);
-		expect(
-			attributeFault(symptoms({ registration: 'roaming', nmActivation: 'disconnected' })),
-		).toBe('network-fault');
-	});
-
-	test('healthy registered+activated modem → indeterminate (no clear fault)', () => {
-		expect(attributeFault(symptoms())).toBe('indeterminate');
-	});
-
-	test('a searching modem is ambiguous → indeterminate', () => {
-		expect(attributeFault(symptoms({ mmState: 'searching', registration: 'searching' }))).toBe(
-			'indeterminate',
-		);
-	});
-
-	test('absent modem on a live source → indeterminate (nothing to attribute)', () => {
-		expect(attributeFault(symptoms({ presence: 'absent', mmState: 'unknown' }))).toBe(
-			'indeterminate',
-		);
-	});
-});
-
-describe('attributeFault — HARD INVARIANT: stale / sourceUnavailable forces indeterminate', () => {
-	test('a STALE source forces indeterminate even when MM says the modem failed', () => {
-		// Without the invariant this would classify modem-fault and could authorise a
-		// disruptive step off data we no longer trust.
-		expect(attributeFault(symptoms({ sourceHealth: 'stale', mmState: 'failed' }))).toBe(
-			'indeterminate',
-		);
-	});
-
-	test('a sourceUnavailable source forces indeterminate even for a clear modem-fault', () => {
-		expect(attributeFault(symptoms({ sourceHealth: 'sourceUnavailable', mmState: 'failed' }))).toBe(
-			'indeterminate',
-		);
-	});
-
-	test('stale input never yields network-fault either', () => {
-		expect(attributeFault(symptoms({ sourceHealth: 'stale', registration: 'denied' }))).toBe(
-			'indeterminate',
-		);
-	});
-});
-
-describe('symptomsFromSnapshot / attributeSnapshot', () => {
-	const identity: ModemIdentity = {
-		equipmentId: imeiEquipmentId('359000000000001'),
-		runtimePath: runtimePath('/org/freedesktop/ModemManager1/Modem/0'),
-	};
-
-	test('projects the attribution-relevant dimensions out of a snapshot', () => {
-		const snapshot = initialSnapshot(identity);
-		expect(symptomsFromSnapshot(snapshot)).toEqual({
-			sourceHealth: 'live',
-			presence: 'absent',
-			mmState: 'unknown',
-			registration: 'unknown',
-			nmActivation: 'unavailable',
-		});
-	});
-
-	test('attributeSnapshot on a fresh (absent) snapshot → indeterminate', () => {
-		expect(attributeSnapshot(initialSnapshot(identity))).toBe('indeterminate');
-	});
-});

package/src/backend/recovery-attribution.ts

@@ -1,86 +0,0 @@
-// 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 type {
-	CellularSnapshot,
-	MmState,
-	NmActivation,
-	Presence,
-	RegistrationStatus,
-	SourceHealth,
-} from '../domain';
-import { isRegistered } from '../domain';
-
-/**
- * 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 function attributeFault(symptoms: FaultSymptoms): FaultAttribution {
-	// 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: CellularSnapshot): FaultSymptoms {
-	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: CellularSnapshot): FaultAttribution {
-	return attributeFault(symptomsFromSnapshot(snapshot));
-}

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

@@ -1,64 +0,0 @@
-// Recovery budget — pure reducer proof: bounded attempts, cooldown refusal, and the
-// loop-stop latch that marks a flapping modem degraded.
-
-import { describe, expect, test } from 'bun:test';
-import { epochMillis } from '../domain';
-import {
-	beginAttempt,
-	INITIAL_BUDGET_STATE,
-	markRecovered,
-	type RecoveryBudget,
-	type RecoveryBudgetState,
-} from './recovery-budget';
-
-const budget: RecoveryBudget = { maxAttempts: 2, cooldownMs: 1000 };
-
-describe('beginAttempt — budget / cooldown / loop-stop', () => {
-	test('a fresh modem proceeds and increments attempts', () => {
-		const decision = beginAttempt(INITIAL_BUDGET_STATE, budget, epochMillis(0));
-		expect(decision.kind).toBe('proceed');
-		expect(decision.state.attempts).toBe(1);
-		expect(decision.state.lastAttemptAt).toBe(epochMillis(0));
-	});
-
-	test('a second attempt sooner than cooldownMs is refused (not counted)', () => {
-		const first = beginAttempt(INITIAL_BUDGET_STATE, budget, epochMillis(0));
-		const second = beginAttempt(first.state, budget, epochMillis(500));
-		expect(second.kind).toBe('cooldown');
-		// Attempts unchanged — a refused attempt does not spend budget.
-		expect(second.state.attempts).toBe(1);
-		if (second.kind === 'cooldown') {
-			expect(second.retryAfter).toBe(epochMillis(1000));
-		}
-	});
-
-	test('exactly maxAttempts proceed, then the loop-stop latches degraded', () => {
-		let state: RecoveryBudgetState = INITIAL_BUDGET_STATE;
-		// Attempt 1 at t=0, attempt 2 at t=1000 (past cooldown) both proceed.
-		const a1 = beginAttempt(state, budget, epochMillis(0));
-		expect(a1.kind).toBe('proceed');
-		state = a1.state;
-		const a2 = beginAttempt(state, budget, epochMillis(1000));
-		expect(a2.kind).toBe('proceed');
-		state = a2.state;
-		expect(state.attempts).toBe(2);
-		// Attempt 3 past cooldown: budget spent → loop-stop, degraded latched.
-		const a3 = beginAttempt(state, budget, epochMillis(2000));
-		expect(a3.kind).toBe('loop-stop');
-		expect(a3.state.degraded).toBe(true);
-	});
-
-	test('once degraded, every further attempt is loop-stopped (latched)', () => {
-		const degraded: RecoveryBudgetState = { attempts: 2, degraded: true };
-		const again = beginAttempt(degraded, budget, epochMillis(999_999));
-		expect(again.kind).toBe('loop-stop');
-		expect(again.state.degraded).toBe(true);
-	});
-
-	test('markRecovered clears the counter and the degraded latch', () => {
-		expect(markRecovered()).toEqual(INITIAL_BUDGET_STATE);
-		const reset = markRecovered();
-		expect(reset.attempts).toBe(0);
-		expect(reset.degraded).toBe(false);
-	});
-});