@ceralive/modem-control 0.2.0 → 1.1.0

package/src/backend/router-ethernet.ts

@@ -1,90 +0,0 @@
-// 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 { type EpochMillis, epochMillis } from '../domain';
-import type { DeviceIfname, RouterHealth, RouterPort, RouterPresence } from '../ports';
-
-/** 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>;
-}
-
-/** The host used for the basic egress-health probe (public DNS anycast). */
-const EGRESS_PROBE_HOST = '1.1.1.1';
-
-async function spawnSucceeds(command: readonly string[]): Promise<boolean> {
-	try {
-		const proc = Bun.spawn([...command], { stdout: 'pipe', stderr: 'pipe' });
-		return (await proc.exited) === 0;
-	} catch {
-		return false;
-	}
-}
-
-async function spawnOutput(command: readonly string[]): Promise<string> {
-	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: DeviceIfname): Promise<boolean> {
-	return spawnSucceeds(['ip', 'link', 'show', 'up', 'dev', String(ifname)]);
-}
-
-async function defaultResolveGateway(ifname: DeviceIfname): Promise<string | undefined> {
-	// `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: string, ifname: DeviceIfname): Promise<boolean> {
-	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: RouterEthernetProbeDeps = {}): RouterPort {
-	const now = deps.now ?? ((): EpochMillis => epochMillis(Date.now()));
-	const checkLinkUp = deps.checkLinkUp ?? defaultCheckLinkUp;
-	const resolveGateway = deps.resolveGateway ?? defaultResolveGateway;
-	const ping = deps.ping ?? defaultPing;
-
-	async function probePresence(ifname: DeviceIfname): Promise<RouterPresence> {
-		return (await checkLinkUp(ifname).catch(() => false)) ? 'present' : 'absent';
-	}
-
-	async function checkHealth(ifname: DeviceIfname): Promise<RouterHealth> {
-		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/src/backend/row-store.ts

@@ -1,105 +0,0 @@
-// 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 {
-	type CellularSnapshot,
-	createSnapshot,
-	revision as makeRevision,
-	markSourceUnavailable,
-	type Revision,
-} from '../domain';
-import type { ObservationFailureReason, ObservationList } from '../ports';
-import type { DecodedManagedObjects } from './managed-objects';
-import { fingerprint, type MappedModem, mapModem, modemPaths } from './mapping';
-
-interface Row {
-	snapshot: CellularSnapshot;
-	fingerprint: string;
-}
-
-export class ObservationRowStore {
-	readonly #rows = new Map<string, Row>();
-	#revCounter = 0;
-	#sourceHealthy = false;
-	#failureReason: ObservationFailureReason = '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: DecodedManagedObjects): boolean {
-		let changed = false;
-		const seen = new Set<string>();
-		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(): boolean {
-		const flipped = !this.#sourceHealthy;
-		this.#sourceHealthy = true;
-		return flipped;
-	}
-
-	/** Flag every row stale (retained, never removed). Returns whether an emission is due. */
-	markUnavailable(reason: ObservationFailureReason): boolean {
-		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(): ObservationList {
-		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: string, mapped: MappedModem): boolean {
-		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(): Revision {
-		this.#revCounter += 1;
-		return makeRevision(this.#revCounter);
-	}
-}

package/src/backend/signal-setup.ts

@@ -1,112 +0,0 @@
-// Signal.Setup(interval) full-lifecycle management, epoch-scoped.
-//
-// ModemManager's `Modem.Signal.Setup(rate)` turns on periodic extended signal
-// reporting. Its lifecycle mirrors the observer's epochs (A3.1):
-//
-//   - applied once when the backend starts observing a modem;
-//   - applied to a hot-plugged modem the moment it appears (`InterfacesAdded`);
-//   - RE-APPLIED to every surviving modem after every owner-epoch change (a fresh MM
-//     owner has none of the previous owner's cadence configured);
-//   - NEVER applied for an OLD epoch — a setup scheduled for an epoch that is no
-//     longer current is dropped before the call ever goes out.
-//
-// A modem that lacks the `Modem.Signal` interface entirely reports
-// `signalCadence: 'unsupported'` and is never called — a soft capability gap, never
-// a start failure. The manager is driven purely by the observer's `onEpochRefresh`
-// hook: every current-epoch snapshot re-drives it, and it de-dupes per (epoch, modem)
-// so a modem is set up exactly once per epoch.
-
-import type { DbusTransport } from '../transport';
-import { MM_BUS_NAME, MODEM_IFACE } from './constants';
-import type { DecodedManagedObjects } from './managed-objects';
-import { hasInterface, pathsWithInterface } from './managed-objects';
-
-/** Whether periodic signal reporting is configured for a modem. */
-export type SignalCadence = 'active' | 'unsupported' | 'unknown';
-
-/** The `Modem.Signal` interface — absent means signal cadence is unsupported. */
-const SIGNAL_IFACE = 'org.freedesktop.ModemManager1.Modem.Signal';
-
-/** MM's default reporting rate is seconds; callers pass whole seconds. */
-export 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 class SignalSetupManager {
-	readonly #transport: DbusTransport;
-	readonly #destination: string;
-	readonly #interval: number;
-	#currentEpoch: string | undefined;
-	// Guards double-issue within an epoch: `${epoch}\u0000${modemPath}`.
-	readonly #applied = new Set<string>();
-	readonly #cadence = new Map<string, SignalCadence>();
-
-	constructor(options: SignalSetupManagerOptions) {
-		this.#transport = options.transport;
-		this.#destination = options.destination ?? MM_BUS_NAME;
-		this.#interval = options.intervalSeconds ?? DEFAULT_SIGNAL_INTERVAL_SECONDS;
-	}
-
-	/** The last-known cadence for a modem path (`'unknown'` until first applied). */
-	cadenceFor(modemPath: string): SignalCadence {
-		return this.#cadence.get(modemPath) ?? 'unknown';
-	}
-
-	/**
-	 * 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 {
-		this.#currentEpoch = epoch;
-		for (const modemPath of pathsWithInterface(tree, MODEM_IFACE)) {
-			const key = `${epoch}\u0000${modemPath}`;
-			if (this.#applied.has(key)) {
-				continue;
-			}
-			this.#applied.add(key);
-			void this.#setupOne(epoch, modemPath, tree);
-		}
-	}
-
-	async #setupOne(epoch: string, modemPath: string, tree: DecodedManagedObjects): Promise<void> {
-		// Epoch changed out from under us before we could issue the call — drop it, so
-		// no Signal.Setup ever fires for a superseded epoch.
-		if (this.#currentEpoch !== epoch) {
-			return;
-		}
-		if (!hasInterface(tree, modemPath, SIGNAL_IFACE)) {
-			this.#cadence.set(modemPath, 'unsupported');
-			return;
-		}
-		if (this.#currentEpoch !== epoch) {
-			return;
-		}
-		try {
-			await this.#transport.callMethod({
-				destination: this.#destination,
-				path: modemPath,
-				interface: SIGNAL_IFACE,
-				member: 'Setup',
-				signature: 'u',
-				args: [this.#interval],
-			});
-			this.#cadence.set(modemPath, 'active');
-		} catch {
-			// A Setup call that errors is a soft gap — surfaced as unsupported, never a
-			// start failure.
-			this.#cadence.set(modemPath, 'unsupported');
-		}
-	}
-}

package/src/backend/sim-unlock.ts

@@ -1,193 +0,0 @@
-// SIM PIN / PUK unlock — read-before-submit, exactly-once, CeraUI-taxonomy-faithful.
-//
-// The ordering is the whole point (mirrors CeraUI `mmcli.ts` unlockSimPin/Puk): the
-// lock state is READ first, and the secret is submitted EXACTLY ONCE. A blind
-// resubmit walks the SIM toward an irreversible PUK / permanent lockout, so on a
-// failure we only RE-READ the lock state to report remaining attempts — we never
-// resubmit. A PUK cannot be cleared with a PIN, so a PUK-locked SIM is surfaced, not
-// submitted into.
-//
-// The result outcomes map onto A2.2's `SimUnlockResult` / `SimPukUnlockResult`, which
-// mirror CeraUI's own shapes so Phase-B adoption is a rename, not a rewrite:
-//   success → unlocked · wrong-pin → incorrect-pin(+remaining) · puk-required →
-//   sim-puk-required · wrong-puk → incorrect-puk(+remaining) · locked(0) →
-//   permanently-blocked · read failure → error · nothing-to-unlock → unlocked.
-// The secret is passed only as a call arg and is NEVER placed in a `reason` string.
-
-import type { SimPukUnlockResult, SimUnlockResult } from '../ports';
-import type { DbusTransport } from '../transport';
-import { MODEM_IFACE, SIM_IFACE } from './constants';
-import {
-	type DecodedManagedObjects,
-	fetchManagedObjects,
-	findInterface,
-	numberProp,
-	propValue,
-	stringProp,
-} from './managed-objects';
-
-// MMModemLock values we branch on.
-const LOCK_SIM_PIN = 2;
-const LOCK_SIM_PUK = 4;
-const LOCK_SIM_PUK2 = 5;
-
-/** A modem's current SIM lock state, read before any submit. */
-interface LockState {
-	readonly required: number;
-	readonly retries: ReadonlyMap<number, number>;
-}
-
-function readLockState(tree: DecodedManagedObjects, modemPath: string): LockState | undefined {
-	const modem = findInterface(tree, modemPath, MODEM_IFACE);
-	if (modem === undefined) {
-		return undefined;
-	}
-	const required = numberProp(modem, 'UnlockRequired') ?? 0;
-	const retries = new Map<number, number>();
-	const raw = propValue(modem, 'UnlockRetries');
-	if (Array.isArray(raw)) {
-		for (const entry of raw) {
-			if (Array.isArray(entry) && typeof entry[0] === 'number' && typeof entry[1] === 'number') {
-				retries.set(entry[0], entry[1]);
-			}
-		}
-	}
-	return { required, retries };
-}
-
-/** The object path of a modem's active SIM (its `Sim` property), when present. */
-function activeSimPath(tree: DecodedManagedObjects, modemPath: string): string | undefined {
-	const path = stringProp(findInterface(tree, modemPath, MODEM_IFACE), 'Sim');
-	return path?.startsWith('/') && path !== '/' ? path : undefined;
-}
-
-const isPukLock = (lock: number): boolean => lock === LOCK_SIM_PUK || lock === LOCK_SIM_PUK2;
-
-/**
- * Submit a SIM PIN read-before-submit and exactly-once. On a wrong PIN the lock state
- * is re-read (never resubmitted) to report remaining attempts or a resulting PUK lock.
- */
-export async function sendSimPin(
-	transport: DbusTransport,
-	destination: string,
-	modemPath: string,
-	pin: string,
-): Promise<SimUnlockResult> {
-	let tree: DecodedManagedObjects;
-	try {
-		tree = await fetchManagedObjects(transport, destination);
-	} catch {
-		return { outcome: 'error', reason: 'could not read modem lock state before PIN submit' };
-	}
-	const state = readLockState(tree, modemPath);
-	if (state === undefined) {
-		return { outcome: 'error', reason: 'modem not found while reading lock state' };
-	}
-	if (isPukLock(state.required)) {
-		return { outcome: 'sim-puk-required', reason: 'SIM is PUK-locked; a PIN cannot clear it' };
-	}
-	if (state.required !== LOCK_SIM_PIN) {
-		return { outcome: 'unlocked', reason: 'no SIM PIN is pending' };
-	}
-	const simPath = activeSimPath(tree, modemPath);
-	if (simPath === undefined) {
-		return { outcome: 'error', reason: 'no active SIM object to submit the PIN to' };
-	}
-	try {
-		await transport.callMethod({
-			destination,
-			path: simPath,
-			interface: SIM_IFACE,
-			member: 'SendPin',
-			signature: 's',
-			args: [pin],
-		});
-		return { outcome: 'unlocked', reason: 'PIN accepted' };
-	} catch {
-		return classifyPinFailure(transport, destination, modemPath);
-	}
-}
-
-async function classifyPinFailure(
-	transport: DbusTransport,
-	destination: string,
-	modemPath: string,
-): Promise<SimUnlockResult> {
-	const state = await readLockState(await fetchManagedObjects(transport, destination), modemPath);
-	if (state !== undefined && isPukLock(state.required)) {
-		return { outcome: 'sim-puk-required', reason: 'wrong PIN tripped the SIM into a PUK lock' };
-	}
-	const remaining = state?.retries.get(LOCK_SIM_PIN);
-	return {
-		outcome: 'incorrect-pin',
-		...(remaining !== undefined ? { remainingAttempts: remaining } : {}),
-		reason: 'PIN was rejected',
-	};
-}
-
-/**
- * Submit a SIM PUK + new PIN read-before-submit and exactly-once. On a wrong PUK the
- * remaining PUK attempts are re-read (never resubmitted); zero remaining is a
- * permanent block.
- */
-export async function sendSimPuk(
-	transport: DbusTransport,
-	destination: string,
-	modemPath: string,
-	puk: string,
-	newPin: string,
-): Promise<SimPukUnlockResult> {
-	let tree: DecodedManagedObjects;
-	try {
-		tree = await fetchManagedObjects(transport, destination);
-	} catch {
-		return { outcome: 'error', reason: 'could not read modem lock state before PUK submit' };
-	}
-	const state = readLockState(tree, modemPath);
-	if (state === undefined) {
-		return { outcome: 'error', reason: 'modem not found while reading lock state' };
-	}
-	if (!isPukLock(state.required)) {
-		return { outcome: 'unlocked', reason: 'no SIM PUK is pending' };
-	}
-	const pukKind = state.required;
-	const simPath = activeSimPath(tree, modemPath);
-	if (simPath === undefined) {
-		return { outcome: 'error', reason: 'no active SIM object to submit the PUK to' };
-	}
-	try {
-		await transport.callMethod({
-			destination,
-			path: simPath,
-			interface: SIM_IFACE,
-			member: 'SendPuk',
-			signature: 'ss',
-			args: [puk, newPin],
-		});
-		return { outcome: 'unlocked', reason: 'PUK accepted; new PIN set' };
-	} catch {
-		return classifyPukFailure(transport, destination, modemPath, pukKind);
-	}
-}
-
-async function classifyPukFailure(
-	transport: DbusTransport,
-	destination: string,
-	modemPath: string,
-	pukKind: number,
-): Promise<SimPukUnlockResult> {
-	const state = await readLockState(await fetchManagedObjects(transport, destination), modemPath);
-	const remaining = state?.retries.get(pukKind);
-	if (remaining === 0) {
-		return {
-			outcome: 'permanently-blocked',
-			remainingAttempts: 0,
-			reason: 'PUK attempts exhausted; SIM is permanently locked',
-		};
-	}
-	return {
-		outcome: 'incorrect-puk',
-		...(remaining !== undefined ? { remainingAttempts: remaining } : {}),
-		reason: 'PUK was rejected',
-	};
-}

package/src/backend/transition-preconditions.ts

@@ -1,149 +0,0 @@
-// USB-mode transition preconditions + the transition interlock seam.
-//
-// The preconditions gate a mode switch and are checked TWICE (draft §rounds 5/6
-// TOCTOU): once at transaction entry (so a doomed request never enters the actor) and
-// again INSIDE the actor (so a request that was valid at entry but became invalid
-// while queued is caught before any disruptive call). `checkTransitionPreconditions`
-// re-polls the LIVE inputs (`probeReadiness`, `interlock.canDisrupt`) each call, so
-// the two checks can genuinely disagree — that disagreement is the TIER-B race.
-//
-// The interlock is BIDIRECTIONAL: `canDisrupt` is the streaming→transition gate (may
-// I disrupt now?), inherited from A3.4's `LifecycleInterlock`; `hold` is the
-// transition→streaming gate (mark "transition active" until released). The Phase-A
-// stub allows both; Phase B wires CeraUI's streaming-admission check into the same
-// interface without changing the transaction.
-
-import type { EpochMillis, IdentityConfidence } from '../domain';
-import type { ConnectionId, DeviceIfname } from '../ports';
-import {
-	type CatalogEntry,
-	type CertifiedCatalog,
-	findCatalogEntry,
-	findPermittedTransition,
-	type MmUsbMode,
-	type PermittedTransition,
-	type SkuDiscriminator,
-} from '../usb-mode';
-import type { InterlockTarget, LifecycleInterlock } from './lifecycle-interlock';
-
-/** A held "transition active" interlock — released when the transaction ends. */
-export interface InterlockHold {
-	release(): Promise<void>;
-}
-
-/**
- * The transition interlock. `canDisrupt` (from `LifecycleInterlock`) answers "is it
- * safe to disrupt this modem now?"; `hold` marks a transition in progress so a
- * streaming start is blocked for its duration. Both directions, one seam.
- */
-export interface TransitionInterlock extends LifecycleInterlock {
-	hold(target: InterlockTarget): Promise<InterlockHold>;
-}
-
-const NO_OP_HOLD: InterlockHold = {
-	release(): Promise<void> {
-		return Promise.resolve();
-	},
-};
-
-/** The Phase-A interlock: always allows, holds nothing. */
-export const ALLOW_ALL_TRANSITION_INTERLOCK: TransitionInterlock = {
-	canDisrupt() {
-		return Promise.resolve({ allow: true } as const);
-	},
-	hold(): Promise<InterlockHold> {
-		return Promise.resolve(NO_OP_HOLD);
-	},
-};
-
-/** Live, re-evaluable readiness inputs — re-polled at entry AND in-actor. */
-export interface TransitionReadiness {
-	/** The identity confidence from A3.2's ladder; `'low'` refuses the transition. */
-	readonly identityConfidence: IdentityConfidence;
-}
-
-/** One USB-mode transition request. */
-export interface UsbModeTransitionRequest {
-	readonly stableKey: string;
-	readonly sku: SkuDiscriminator;
-	readonly fromMode: MmUsbMode;
-	readonly toMode: MmUsbMode;
-	readonly connectionId: ConnectionId;
-	readonly deviceIfname: DeviceIfname;
-	/** Physical-topology UID captured BEFORE the switch — survives re-enumeration. */
-	readonly cachedPhysicalUid: string;
-	/** The MM `Device` UID to inhibit by (cached — the modem disappears mid-switch). */
-	readonly inhibitUid: string;
-	/** Must be `true` (mirrors the CLI `--confirm` flag). */
-	readonly confirm: boolean;
-	/** Must be `true` (an extra maintenance-mode safety gate). */
-	readonly maintenance: boolean;
-	readonly now: EpochMillis;
-	/** Live readiness, re-polled at entry AND in-actor (TOCTOU-safe). */
-	probeReadiness(): Promise<TransitionReadiness>;
-}
-
-/** How a transition ended. */
-export type UsbModeTransitionOutcome =
-	| {
-			readonly status: 'refused';
-			readonly stage: 'entry' | 'in-actor';
-			readonly reason: string;
-			readonly steps: readonly string[];
-	  }
-	| {
-			readonly status: 'succeeded';
-			readonly newIfname: DeviceIfname;
-			readonly steps: readonly string[];
-	  }
-	| {
-			readonly status: 'failed';
-			readonly degraded: boolean;
-			readonly reason: string;
-			readonly steps: readonly string[];
-	  };
-
-/** The result of a precondition check — the matched entry/transition, or a reason. */
-export type PreconditionResult =
-	| { readonly ok: true; readonly entry: CatalogEntry; readonly transition: PermittedTransition }
-	| { readonly ok: false; readonly reason: string };
-
-/**
- * Check every transition precondition against the LIVE inputs. Called at entry and
- * again in-actor; a request that passed at entry can fail here if the identity
- * confidence dropped or the interlock closed in the meantime. Order is cheap-static
- * checks first (confirm, maintenance, catalog, permitted) then the live probes
- * (identity, interlock), so a refusal touches as little as possible.
- */
-export async function checkTransitionPreconditions(
-	request: UsbModeTransitionRequest,
-	catalog: CertifiedCatalog,
-	interlock: TransitionInterlock,
-): Promise<PreconditionResult> {
-	if (!request.confirm) {
-		return { ok: false, reason: 'confirm:true is required (missing --confirm)' };
-	}
-	if (!request.maintenance) {
-		return { ok: false, reason: 'maintenance flag is required' };
-	}
-	const entry = findCatalogEntry(catalog, request.sku);
-	if (entry === undefined) {
-		return { ok: false, reason: `uncertified SKU ${request.sku.vidPid} ${request.sku.model}` };
-	}
-	const transition = findPermittedTransition(entry, request.fromMode, request.toMode);
-	if (transition === undefined) {
-		return {
-			ok: false,
-			reason: `transition ${request.fromMode}->${request.toMode} not permitted for ${request.sku.model}`,
-		};
-	}
-	const readiness = await request.probeReadiness();
-	if (readiness.identityConfidence === 'low') {
-		return { ok: false, reason: 'low-confidence identity — refusing to transition' };
-	}
-	const verdict = await interlock.canDisrupt({ stableKey: request.stableKey });
-	if (!verdict.allow) {
-		return { ok: false, reason: `interlock held: ${verdict.reason}` };
-	}
-	return { ok: true, entry, transition };
-}