@ceralive/modem-control 0.2.0 → 1.1.0

package/src/backend/usb-mode-transition.test.ts

@@ -1,323 +0,0 @@
-// The transition transaction — the safety-critical core. This proves:
-//   - the happy path walks all TEN steps in order and yields a NEW ifname on the SAME
-//     stableKey;
-//   - the THREE-TIER negative matrix: TIER A entry refusals fire ZERO actor/lease/AT
-//     calls; TIER B an in-actor race is caught after exactly one actor entry with zero
-//     lease/AT; TIER C a postcondition mismatch fails degraded, never reactivates, and
-//     still releases the interlock via finally;
-//   - a crash mid-transaction trips the watchdog, force-uninhibits, and returns
-//     degraded rather than hanging forever.
-
-import { describe, expect, test } from 'bun:test';
-import { epochMillis } from '../domain';
-import { connectionId, deviceIfname, type NetworkManagerPort, receipt } from '../ports';
-import type { UsbDeviceSnapshot } from './device-classifier';
-import { ModemActor } from './modem-actor';
-import type { TransitionInterlock, UsbModeTransitionRequest } from './transition-preconditions';
-import { UsbModeTransition, type UsbModeTransitionDeps } from './usb-mode-transition';
-
-const CACHED_UID = 'pci-0000:00-usb-0:1';
-const SKU = {
-	vidPid: '2c7c:0125',
-	model: 'CERALIVE-SYNTHETIC-TEST-SKU',
-	firmwarePrefix: 'SYNTHETICFW01',
-};
-
-const TEN_STEPS = [
-	'nm-quiesce',
-	'inhibit',
-	'at-command',
-	'await-port-drop',
-	'uninhibit',
-	'await-reenumeration',
-	'postcondition',
-	'resolve-ifname',
-	'reactivate',
-	'release-interlock',
-];
-
-const OLD_QMI: UsbDeviceSnapshot = {
-	vendorId: '2c7c',
-	productId: '0125',
-	bDeviceClass: 0,
-	physicalUid: CACHED_UID,
-	ifname: 'wwan0',
-	interfaces: [
-		{ interfaceClass: 0xff, interfaceSubClass: 0xff, interfaceProtocol: 0xff, driver: 'qmi_wwan' },
-	],
-};
-
-/** Re-enumerated as MBIM (target), same physical UID, NEW ifname — matches the catalog. */
-const NEW_MBIM: UsbDeviceSnapshot = {
-	vendorId: '2c7c',
-	productId: '0126',
-	bDeviceClass: 0,
-	physicalUid: CACHED_UID,
-	ifname: 'wwan1',
-	interfaces: [
-		{ interfaceClass: 0x02, interfaceSubClass: 0x0e, interfaceProtocol: 0x00, driver: 'cdc_mbim' },
-		{ interfaceClass: 0x0a, interfaceSubClass: 0x00, interfaceProtocol: 0x02, driver: 'cdc_mbim' },
-	],
-};
-
-/** Re-enumerated STILL as QMI — the postcondition-mismatch device (same UID). */
-const STILL_QMI: UsbDeviceSnapshot = { ...OLD_QMI, ifname: 'wwan0' };
-
-interface SpyLog {
-	readonly calls: string[];
-}
-
-function makeNm(log: SpyLog): NetworkManagerPort {
-	const rcpt = () => receipt('connection', 'applied', 'ok');
-	return {
-		createGsmProfile: () => Promise.reject(new Error('unused')),
-		readGsmProfile: () => Promise.resolve(undefined),
-		updateGsmProfile: () => Promise.reject(new Error('unused')),
-		deleteGsmProfile: () => Promise.resolve(),
-		activate: (_id, ifname) => {
-			log.calls.push(`nm.activate:${ifname}`);
-			return Promise.resolve(rcpt());
-		},
-		deactivate: () => Promise.resolve(rcpt()),
-		acquireQuiesceLease: (id, ifname) => {
-			log.calls.push('nm.acquireQuiesceLease');
-			return Promise.resolve({
-				connectionId: id,
-				deviceIfname: ifname,
-				acquiredAt: epochMillis(0),
-			});
-		},
-		releaseQuiesceLease: () => {
-			log.calls.push('nm.releaseQuiesceLease');
-			return Promise.resolve();
-		},
-	};
-}
-
-function makeMm(log: SpyLog): Pick<UsbModeTransitionDeps['modemManager'], 'inhibit' | 'uninhibit'> {
-	return {
-		inhibit: (uid) => {
-			log.calls.push(`mm.inhibit:${uid}`);
-			return Promise.resolve({ uid, acquiredAt: epochMillis(0) });
-		},
-		uninhibit: () => {
-			log.calls.push('mm.uninhibit');
-			return Promise.resolve();
-		},
-	};
-}
-
-function okSender(log: SpyLog): UsbModeTransitionDeps['atSender'] {
-	return {
-		send: (command) => {
-			log.calls.push(`at.send:${command}`);
-			return Promise.resolve({ ok: true, raw: 'OK' });
-		},
-	};
-}
-
-function scriptedEnumerate(
-	frames: UsbDeviceSnapshot[][],
-): () => Promise<readonly UsbDeviceSnapshot[]> {
-	let i = 0;
-	return () => {
-		const frame = frames[Math.min(i, frames.length - 1)] ?? [];
-		i += 1;
-		return Promise.resolve(frame);
-	};
-}
-
-function makeRequest(overrides: Partial<UsbModeTransitionRequest> = {}): UsbModeTransitionRequest {
-	return {
-		stableKey: 'slot:test',
-		sku: SKU,
-		fromMode: 'qmi',
-		toMode: 'mbim',
-		connectionId: connectionId('uuid-1'),
-		deviceIfname: deviceIfname('wwan0'),
-		cachedPhysicalUid: CACHED_UID,
-		inhibitUid: CACHED_UID,
-		confirm: true,
-		maintenance: true,
-		now: epochMillis(0),
-		probeReadiness: () => Promise.resolve({ identityConfidence: 'high' }),
-		...overrides,
-	};
-}
-
-function makeTransition(
-	log: SpyLog,
-	overrides: Partial<UsbModeTransitionDeps> = {},
-): UsbModeTransition {
-	return new UsbModeTransition({
-		actor: new ModemActor(),
-		nm: makeNm(log),
-		modemManager: makeMm(log),
-		atSender: okSender(log),
-		enumerate: scriptedEnumerate([[OLD_QMI], [], [NEW_MBIM]]),
-		reenumerationTimeoutMs: 500,
-		pollIntervalMs: 1,
-		watchdogMs: 200,
-		...overrides,
-	});
-}
-
-describe('UsbModeTransition — the happy path walks all ten steps', () => {
-	test('a certified qmi→mbim transition succeeds with a NEW ifname on the same stableKey', async () => {
-		const log: SpyLog = { calls: [] };
-		const transition = makeTransition(log);
-		const request = makeRequest();
-		const outcome = await transition.execute(request);
-
-		expect(outcome.status).toBe('succeeded');
-		if (outcome.status !== 'succeeded') {
-			return;
-		}
-		// The row survives with the SAME stableKey but a NEW ifname.
-		expect(request.stableKey).toBe('slot:test');
-		expect(String(outcome.newIfname)).toBe('wwan1');
-		expect(String(request.deviceIfname)).toBe('wwan0');
-		// All ten goal steps, in order.
-		expect(outcome.steps.filter((s) => TEN_STEPS.includes(s))).toEqual(TEN_STEPS);
-		// The catalog command was sent exactly once; reactivation targeted the new ifname.
-		expect(log.calls.filter((c) => c.startsWith('at.send:'))).toEqual([
-			'at.send:AT+QCFG="usbnet",2',
-		]);
-		expect(log.calls).toContain('nm.activate:wwan1');
-	});
-});
-
-/** No nm/mm/at side-effecting call ran, and the actor was never entered. */
-function expectZeroSideEffects(log: SpyLog, steps: readonly string[]): void {
-	expect(log.calls).toEqual([]);
-	expect(steps).not.toContain('actor-enter');
-}
-
-describe('UsbModeTransition — TIER A: entry refusals fire ZERO actor/lease/AT calls', () => {
-	const cases: Array<[string, Partial<UsbModeTransitionRequest>]> = [
-		['unconfirmed (confirm:false)', { confirm: false }],
-		['uncertified SKU (no catalog entry)', { sku: { ...SKU, firmwarePrefix: 'UNKNOWNFW' } }],
-		[
-			'non-permitted transition (mbim→ecm-ncm not certified)',
-			{ fromMode: 'mbim', toMode: 'ecm-ncm' },
-		],
-		[
-			'ambiguous / low-confidence identity',
-			{ probeReadiness: () => Promise.resolve({ identityConfidence: 'low' }) },
-		],
-		['missing maintenance flag', { maintenance: false }],
-	];
-	for (const [name, overrides] of cases) {
-		test(name, async () => {
-			const log: SpyLog = { calls: [] };
-			const transition = makeTransition(log);
-			const outcome = await transition.execute(makeRequest(overrides));
-			expect(outcome.status).toBe('refused');
-			if (outcome.status === 'refused') {
-				expect(outcome.stage).toBe('entry');
-			}
-			expectZeroSideEffects(log, outcome.steps);
-		});
-	}
-
-	test('interlock already held → refused at entry, hold never acquired', async () => {
-		const log: SpyLog = { calls: [] };
-		const heldInterlock: TransitionInterlock = {
-			canDisrupt: () => Promise.resolve({ allow: false, reason: 'a stream is admitted' }),
-			hold: () => Promise.reject(new Error('hold must not be acquired')),
-		};
-		const transition = makeTransition(log, { interlock: heldInterlock });
-		const outcome = await transition.execute(makeRequest());
-		expect(outcome.status).toBe('refused');
-		expectZeroSideEffects(log, outcome.steps);
-	});
-});
-
-describe('UsbModeTransition — TIER B: an in-actor race is caught with zero lease/AT', () => {
-	test('valid at entry, invalid in-actor → one actor entry, zero lease/AT calls', async () => {
-		const log: SpyLog = { calls: [] };
-		let probes = 0;
-		const transition = makeTransition(log, {});
-		const request = makeRequest({
-			// High at entry, low by the time the actor runs (a duplicate IMEI appeared).
-			probeReadiness: () => {
-				probes += 1;
-				return Promise.resolve({ identityConfidence: probes === 1 ? 'high' : 'low' });
-			},
-		});
-		const outcome = await transition.execute(request);
-
-		expect(outcome.status).toBe('refused');
-		if (outcome.status === 'refused') {
-			expect(outcome.stage).toBe('in-actor');
-		}
-		// Exactly one actor entry.
-		expect(outcome.steps.filter((s) => s === 'actor-enter')).toEqual(['actor-enter']);
-		// Zero lease/AT (and zero nm/mm) calls fired.
-		expect(log.calls).toEqual([]);
-	});
-});
-
-describe('UsbModeTransition — TIER C: a postcondition mismatch fails degraded', () => {
-	test('AT returned OK but the device stayed qmi → FAILED+degraded, NO reactivation, interlock released', async () => {
-		const log: SpyLog = { calls: [] };
-		let holdReleases = 0;
-		const interlock: TransitionInterlock = {
-			canDisrupt: () => Promise.resolve({ allow: true }),
-			hold: () =>
-				Promise.resolve({
-					release: () => {
-						holdReleases += 1;
-						return Promise.resolve();
-					},
-				}),
-		};
-		const transition = makeTransition(log, {
-			interlock,
-			// Re-enumerates STILL as qmi — the switch did not take, even though AT said OK.
-			enumerate: scriptedEnumerate([[OLD_QMI], [], [STILL_QMI]]),
-		});
-		const outcome = await transition.execute(makeRequest());
-
-		expect(outcome.status).toBe('failed');
-		if (outcome.status === 'failed') {
-			expect(outcome.degraded).toBe(true);
-			expect(outcome.reason).toContain('postcondition mismatch');
-		}
-		// The AT command WAS sent (OK ignored) but reactivation NEVER happened.
-		expect(log.calls.filter((c) => c.startsWith('at.send:'))).toHaveLength(1);
-		expect(log.calls.some((c) => c.startsWith('nm.activate:'))).toBe(false);
-		expect(outcome.steps).not.toContain('reactivate');
-		// The interlock hook was released via finally, on the failure path.
-		expect(outcome.steps).toContain('release-interlock');
-		expect(holdReleases).toBe(1);
-	});
-});
-
-describe('UsbModeTransition — crash mid-transaction trips the watchdog', () => {
-	test('a hung AT command force-uninhibits, reprobes, and returns degraded (never hangs)', async () => {
-		const log: SpyLog = { calls: [] };
-		const hangingSender: UsbModeTransitionDeps['atSender'] = {
-			send: (command) => {
-				log.calls.push(`at.send:${command}`);
-				return new Promise(() => undefined);
-			},
-		};
-		const transition = makeTransition(log, {
-			atSender: hangingSender,
-			enumerate: scriptedEnumerate([[OLD_QMI]]),
-			watchdogMs: 30,
-		});
-		const outcome = await transition.execute(makeRequest());
-
-		expect(outcome.status).toBe('failed');
-		if (outcome.status === 'failed') {
-			expect(outcome.degraded).toBe(true);
-			expect(outcome.reason).toContain('timed out');
-		}
-		// The watchdog force-uninhibited the modem and released the interlock.
-		expect(outcome.steps).toContain('force-uninhibit');
-		expect(outcome.steps).toContain('release-interlock');
-		expect(log.calls).toContain('mm.uninhibit');
-	});
-});

package/src/backend/usb-mode-transition.ts

@@ -1,253 +0,0 @@
-// The certified USB-mode transition transaction.
-//
-// A mode switch is destructive: the modem physically re-enumerates, its interface
-// name changes, and MM briefly loses sight of it. This transaction runs the switch
-// through A3.3's shared per-modem `ModemActor` (keyed on stableKey, so it serialises
-// behind every other disruptive op) in a FIXED order:
-//
-//   1 NM-quiesce → 2 inhibit-by-cached-UID → 3 AT command → 4 expected port-drop →
-//   5 uninhibit → 6 await SAME physical UID → 7 POSTCONDITION → 8 resolve new ifname →
-//   9 reactivate (uuid, newIfname) → 10 release interlock (finally, always).
-//
-// THE POSTCONDITION IS THE ONLY PROOF OF SUCCESS. An AT `OK` proves nothing — only a
-// re-enumerated device whose descriptors AND observed mode equal the catalog target
-// counts. On a postcondition MISMATCH the whole transaction fails `degraded`, does NOT
-// reactivate, and still releases the interlock via `finally`. A hung command trips the
-// AT watchdog, which force-uninhibits so the system reprobes rather than wedging.
-
-import type { DeviceIfname, InhibitLease, ModemManagerPort, NetworkManagerPort } from '../ports';
-import { deviceIfname } from '../ports';
-import { CERTIFIED_CATALOG, type CertifiedCatalog, type PermittedTransition } from '../usb-mode';
-import {
-	type AtAuditSink,
-	AtCommandLease,
-	type AtCommandSender,
-	computeAtAllowlist,
-} from './at-lease';
-import { descriptorsMatch, detectUsbMode, type UsbDeviceSnapshot } from './device-classifier';
-import type { ModemActor } from './modem-actor';
-import {
-	ALLOW_ALL_TRANSITION_INTERLOCK,
-	checkTransitionPreconditions,
-	type TransitionInterlock,
-	type UsbModeTransitionOutcome,
-	type UsbModeTransitionRequest,
-} from './transition-preconditions';
-
-const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
-
-const DEFAULT_WATCHDOG_MS = 30_000;
-const DEFAULT_REENUM_TIMEOUT_MS = 60_000;
-const DEFAULT_POLL_INTERVAL_MS = 250;
-
-/** Construction dependencies for the transition. Everything I/O is injectable. */
-export interface UsbModeTransitionDeps {
-	readonly actor: ModemActor;
-	readonly nm: NetworkManagerPort;
-	readonly modemManager: Pick<ModemManagerPort, 'inhibit' | 'uninhibit'>;
-	readonly atSender: AtCommandSender;
-	/** Refresh-triggered USB enumeration (e.g. `createUsbEnumerator().enumerate`). */
-	readonly enumerate: () => Promise<readonly UsbDeviceSnapshot[]>;
-	readonly interlock?: TransitionInterlock;
-	readonly catalog?: CertifiedCatalog;
-	readonly audit?: AtAuditSink;
-	readonly resolveIfname?: (device: UsbDeviceSnapshot) => DeviceIfname | undefined;
-	readonly watchdogMs?: number;
-	readonly reenumerationTimeoutMs?: number;
-	readonly pollIntervalMs?: number;
-}
-
-function defaultResolveIfname(device: UsbDeviceSnapshot): DeviceIfname | undefined {
-	return device.ifname !== undefined && device.ifname !== ''
-		? deviceIfname(device.ifname)
-		: undefined;
-}
-
-/** The USB-mode transition transaction. One instance is reusable across requests. */
-export class UsbModeTransition {
-	readonly #actor: ModemActor;
-	readonly #nm: NetworkManagerPort;
-	readonly #modemManager: Pick<ModemManagerPort, 'inhibit' | 'uninhibit'>;
-	readonly #atSender: AtCommandSender;
-	readonly #enumerate: () => Promise<readonly UsbDeviceSnapshot[]>;
-	readonly #interlock: TransitionInterlock;
-	readonly #catalog: CertifiedCatalog;
-	readonly #audit: AtAuditSink | undefined;
-	readonly #resolveIfname: (device: UsbDeviceSnapshot) => DeviceIfname | undefined;
-	readonly #watchdogMs: number;
-	readonly #reenumMs: number;
-	readonly #pollMs: number;
-
-	constructor(deps: UsbModeTransitionDeps) {
-		this.#actor = deps.actor;
-		this.#nm = deps.nm;
-		this.#modemManager = deps.modemManager;
-		this.#atSender = deps.atSender;
-		this.#enumerate = deps.enumerate;
-		this.#interlock = deps.interlock ?? ALLOW_ALL_TRANSITION_INTERLOCK;
-		this.#catalog = deps.catalog ?? CERTIFIED_CATALOG;
-		this.#audit = deps.audit;
-		this.#resolveIfname = deps.resolveIfname ?? defaultResolveIfname;
-		this.#watchdogMs = deps.watchdogMs ?? DEFAULT_WATCHDOG_MS;
-		this.#reenumMs = deps.reenumerationTimeoutMs ?? DEFAULT_REENUM_TIMEOUT_MS;
-		this.#pollMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-	}
-
-	/** Run one transition. Preconditions are checked at entry, then again in-actor. */
-	async execute(request: UsbModeTransitionRequest): Promise<UsbModeTransitionOutcome> {
-		const steps: string[] = [];
-		// ENTRY check — a doomed request NEVER enters the actor (TIER A: zero calls).
-		const entry = await checkTransitionPreconditions(request, this.#catalog, this.#interlock);
-		if (!entry.ok) {
-			return { status: 'refused', stage: 'entry', reason: entry.reason, steps };
-		}
-		return this.#actor.run(request.stableKey, () => this.#inActor(request, steps));
-	}
-
-	async #inActor(
-		request: UsbModeTransitionRequest,
-		steps: string[],
-	): Promise<UsbModeTransitionOutcome> {
-		steps.push('actor-enter');
-		// IN-ACTOR re-check — catches a race that closed a gate while queued (TIER B).
-		const recheck = await checkTransitionPreconditions(request, this.#catalog, this.#interlock);
-		if (!recheck.ok) {
-			return { status: 'refused', stage: 'in-actor', reason: recheck.reason, steps };
-		}
-		const hold = await this.#interlock.hold({ stableKey: request.stableKey });
-		try {
-			return await this.#runTransaction(
-				request,
-				recheck.entry.permittedTransitions,
-				recheck.transition,
-				steps,
-			);
-		} finally {
-			steps.push('release-interlock');
-			await hold.release().catch(() => undefined);
-		}
-	}
-
-	async #runTransaction(
-		request: UsbModeTransitionRequest,
-		allCommands: readonly PermittedTransition[],
-		transition: PermittedTransition,
-		steps: string[],
-	): Promise<UsbModeTransitionOutcome> {
-		let inhibit: InhibitLease | undefined;
-		let reactivated = false;
-		const forceUninhibit = async (): Promise<void> => {
-			if (inhibit === undefined) {
-				return;
-			}
-			const held = inhibit;
-			inhibit = undefined;
-			steps.push('force-uninhibit');
-			await this.#modemManager.uninhibit(held).catch(() => undefined);
-		};
-		const lease = new AtCommandLease({
-			sender: this.#atSender,
-			allowlist: computeAtAllowlist(allCommands.map((t) => t.atCommand)),
-			timeoutMs: this.#watchdogMs,
-			onWatchdog: forceUninhibit,
-			...(this.#audit !== undefined ? { audit: this.#audit } : {}),
-		});
-
-		steps.push('nm-quiesce');
-		const quiesce = await this.#nm.acquireQuiesceLease(request.connectionId, request.deviceIfname);
-		try {
-			steps.push('inhibit');
-			inhibit = await this.#modemManager.inhibit(request.inhibitUid);
-
-			// AT `OK` is IGNORED for success — only the postcondition below decides.
-			steps.push('at-command');
-			await lease.run(transition.atCommand, { inhibitUid: request.inhibitUid });
-
-			steps.push('await-port-drop');
-			await this.#awaitPortDrop(request.cachedPhysicalUid);
-
-			steps.push('uninhibit');
-			if (inhibit !== undefined) {
-				const held = inhibit;
-				inhibit = undefined;
-				await this.#modemManager.uninhibit(held);
-			}
-
-			steps.push('await-reenumeration');
-			const device = await this.#awaitReenumeration(request.cachedPhysicalUid);
-
-			steps.push('postcondition');
-			const observedMode = detectUsbMode(device);
-			const descriptorsOk = descriptorsMatch(device, transition.expectedDescriptors);
-			if (observedMode !== request.toMode || !descriptorsOk) {
-				return {
-					status: 'failed',
-					degraded: true,
-					reason: `postcondition mismatch: observed ${observedMode ?? 'unknown'} vs target ${request.toMode}; descriptors ${descriptorsOk ? 'ok' : 'mismatch'}`,
-					steps,
-				};
-			}
-
-			steps.push('resolve-ifname');
-			const newIfname = this.#resolveIfname(device);
-			if (newIfname === undefined) {
-				return { status: 'failed', degraded: true, reason: 'could not resolve new ifname', steps };
-			}
-
-			steps.push('reactivate');
-			await this.#nm.activate(request.connectionId, newIfname);
-			reactivated = true;
-			return { status: 'succeeded', newIfname, steps };
-		} catch (error) {
-			await forceUninhibit();
-			await this.#reprobe();
-			return {
-				status: 'failed',
-				degraded: true,
-				reason: error instanceof Error ? error.message : String(error),
-				steps,
-			};
-		} finally {
-			await forceUninhibit();
-			if (!reactivated) {
-				// Failure path: restore the old connection. On success the new-ifname
-				// activation supersedes the quiesce lease (old ifname is gone).
-				steps.push('release-quiesce');
-				await this.#nm.releaseQuiesceLease(quiesce).catch(() => undefined);
-			}
-		}
-	}
-
-	async #awaitPortDrop(uid: string): Promise<void> {
-		const deadline = Date.now() + this.#reenumMs;
-		while (Date.now() < deadline) {
-			const devices = await this.#enumerate();
-			if (!devices.some((d) => d.physicalUid === uid)) {
-				return;
-			}
-			await sleep(this.#pollMs);
-		}
-		throw new Error(`control port did not drop within ${this.#reenumMs}ms (uid ${uid})`);
-	}
-
-	async #awaitReenumeration(uid: string): Promise<UsbDeviceSnapshot> {
-		const deadline = Date.now() + this.#reenumMs;
-		while (Date.now() < deadline) {
-			const devices = await this.#enumerate();
-			const device = devices.find((d) => d.physicalUid === uid);
-			if (device !== undefined) {
-				return device;
-			}
-			await sleep(this.#pollMs);
-		}
-		throw new Error(`device did not re-enumerate within ${this.#reenumMs}ms (uid ${uid})`);
-	}
-
-	/** Best-effort state re-read after a crash — the transaction still fails degraded. */
-	async #reprobe(): Promise<void> {
-		await this.#enumerate().then(
-			() => undefined,
-			() => undefined,
-		);
-	}
-}

package/src/domain/brand.ts

@@ -1,29 +0,0 @@
-// Nominal (branded) primitive types for the domain layer.
-//
-// Branding stops the four identity strings — and the two counter numbers — from
-// being interchangeable at the type level: a `LogicalSlotId` can never be passed
-// where a `SubscriptionId` is expected, even though both are strings at runtime.
-// Downstream waves (A2.2 ports, A3.x D-Bus backend) depend on this distinction.
-
-import { DomainError } from './errors';
-
-declare const brand: unique symbol;
-
-/** A primitive `T` tagged with a compile-time-only brand `B`. Erased at runtime. */
-export type Brand<T, B extends string> = T & { readonly [brand]: B };
-
-/** Assert a value is a non-empty string, throwing a typed error otherwise. */
-export function nonEmptyString(value: string, label: string): string {
-	if (value.length === 0) {
-		throw new DomainError(`${label} must be a non-empty string`);
-	}
-	return value;
-}
-
-/** Assert a value is a non-negative safe integer, throwing a typed error otherwise. */
-export function nonNegativeInteger(value: number, label: string): number {
-	if (!Number.isSafeInteger(value) || value < 0) {
-		throw new DomainError(`${label} must be a non-negative safe integer, got ${value}`);
-	}
-	return value;
-}

package/src/domain/errors.ts

@@ -1,77 +0,0 @@
-// Typed errors for the domain layer.
-//
-// The domain never fails silently: an impossible state combination, a refused
-// policy binding, or a non-monotonic revision each raise a distinct, catchable
-// error class carrying a machine-readable reason. QA and callers discriminate on
-// the class and the `code`, never on a message string.
-
-/** Base class for every domain-layer error. Callers can catch this to trap all. */
-export class DomainError extends Error {
-	override readonly name: string = 'DomainError';
-
-	constructor(message: string) {
-		super(message);
-		// Restore the prototype chain across the ES5 target transpile so
-		// `instanceof` works on subclasses (standard TS extends-Error guard).
-		Object.setPrototypeOf(this, new.target.prototype);
-	}
-}
-
-/**
- * Every distinct impossible cross-dimension combination the guards reject.
- * One code per rule so a failing construction names exactly what it violated.
- */
-export type ImpossibleStateCode =
-	| 'registered-while-absent'
-	| 'registered-radio-off'
-	| 'registered-empty-rat-set'
-	| 'active-state-while-absent'
-	| 'radio-off-while-active'
-	| 'nm-activated-while-absent'
-	| 'nm-activated-without-interface'
-	| 'nm-activated-without-mm-connected'
-	| 'multiple-active-sim-slots'
-	| 'locked-sim-in-empty-slot'
-	| 'mm-locked-without-sim-lock'
-	| 'data-interface-name-without-presence'
-	| 'recovery-attempts-negative'
-	| 'recovery-cooldown-stage-mismatch'
-	| 'recovery-idle-with-attempts';
-
-/** A snapshot was constructed (or transitioned into) a physically impossible state. */
-export class ImpossibleStateError extends DomainError {
-	override readonly name = 'ImpossibleStateError';
-	readonly code: ImpossibleStateCode;
-
-	constructor(code: ImpossibleStateCode, detail: string) {
-		super(`impossible cellular state [${code}]: ${detail}`);
-		this.code = code;
-	}
-}
-
-/**
- * A durable policy binding was attempted against an identity that is not allowed
- * to carry one — today only low-confidence (ambiguous) equipment identities.
- */
-export class PolicyBindingRefusedError extends DomainError {
-	override readonly name = 'PolicyBindingRefusedError';
-	readonly reason: 'ambiguous-identity';
-
-	constructor(detail: string) {
-		super(`durable policy binding refused: ${detail}`);
-		this.reason = 'ambiguous-identity';
-	}
-}
-
-/** A snapshot transition tried to keep or lower the monotonic revision. */
-export class RevisionMonotonicityError extends DomainError {
-	override readonly name = 'RevisionMonotonicityError';
-	readonly previous: number;
-	readonly next: number;
-
-	constructor(previous: number, next: number) {
-		super(`revision must strictly increase: ${previous} -> ${next}`);
-		this.previous = previous;
-		this.next = next;
-	}
-}