@ceralive/modem-control 0.1.0 → 1.0.0

package/src/usb-mode/ingestion.ts

@@ -0,0 +1,297 @@
+// The evidence-bundle ingestion seam — turning ONE real `certify` bundle into (i) a
+// classifier test fixture in the real udev shape and (ii) a candidate catalog entry.
+//
+// This is the documented path between the bench and the catalog. It is deliberately a
+// PURE TRANSFORM that produces a REVIEW ARTIFACT: nothing here writes a file, mutates
+// `certified-catalog.json`, or promotes anything. A catalog addition stays what Phase A
+// made it — a human-reviewed commit — and this seam only removes the hand-transcription
+// step between the bundle and that commit.
+//
+// THE ONE RULE THE CODE ENFORCES, NOT THE REVIEWER:
+//   A bundle marked `synthetic: true` is REFUSED for catalog promotion, with a typed
+//   reason. Synthetic bundles are legitimate test data — `buildClassifierFixture` accepts
+//   them and stamps the fixture's provenance with `synthetic: true` — but a catalog entry
+//   asserts a certified hardware fact, and no synthetic capture may ever back one.
+//
+// SHAPE COMPATIBILITY, not shape duplication: the bundle is validated here through a
+// deliberately NON-strict VIEW schema. The authoritative bundle schema lives beside the
+// `certify` command in the CLI, which depends on this package and not the reverse, so
+// this file describes only the subset ingestion reads and ignores the rest (`lsusb`,
+// `modemManager`, the transition timeline). Adding a field to the bundle can therefore
+// never break ingestion — which is the point of a view.
+
+import { z } from 'zod';
+import type { UsbDeviceSnapshot } from '../backend/device-classifier';
+import {
+	CANONICAL_USB_MODES,
+	type CanonicalUsbMode,
+	type CatalogEntry,
+	catalogEntrySchema,
+	expectedDescriptorsSchema,
+	MM_USB_MODES,
+} from './catalog-schema';
+import { parseUsbDevices, selectUniqueDevice } from './usb-devices-parse';
+
+const mmMode = z.enum(MM_USB_MODES);
+
+/** The ingestion VIEW of a certification bundle — non-strict on purpose (see header). */
+export const evidenceBundleViewSchema = z.object({
+	schemaVersion: z.literal(1),
+	synthetic: z.boolean(),
+	capturedAtMs: z.number(),
+	slot: z.string().min(1),
+	sku: z
+		.object({
+			vidPid: z.string().regex(/^[0-9a-f]{4}:[0-9a-f]{4}$/),
+			model: z.string().min(1),
+			firmwarePrefix: z.string().min(1),
+		})
+		.optional(),
+	usb: z.object({
+		usbDevices: z.string().min(1),
+		udevProperties: z.record(z.string(), z.string()),
+	}),
+	transition: z
+		.object({
+			from: mmMode,
+			to: mmMode,
+			atCommand: z.string().min(1),
+			expectedResponse: z.string().min(1),
+			expectsPortDrop: z.boolean(),
+			afterDescriptors: expectedDescriptorsSchema,
+		})
+		.optional(),
+});
+export type EvidenceBundleView = z.infer<typeof evidenceBundleViewSchema>;
+
+/** Every way ingestion can refuse. Each is a named, actionable condition — never a throw. */
+export type IngestionRefusalReason =
+	| 'bundle-malformed'
+	| 'sha256-malformed'
+	| 'sku-missing'
+	| 'device-not-in-capture'
+	| 'device-ambiguous'
+	| 'no-interfaces-captured'
+	| 'synthetic-bundle'
+	| 'transition-mode-mismatch'
+	| 'entry-schema-invalid';
+
+/** A typed refusal. `detail` is for a human reviewer; `reason` is for a machine. */
+export interface IngestionRefusal {
+	readonly ok: false;
+	readonly reason: IngestionRefusalReason;
+	readonly detail: string;
+}
+
+/** A refusal or a value — ingestion never throws and never returns a partial result. */
+export type IngestionOutcome<T> = { readonly ok: true; readonly value: T } | IngestionRefusal;
+
+const refuse = (reason: IngestionRefusalReason, detail: string): IngestionRefusal => ({
+	ok: false,
+	reason,
+	detail,
+});
+
+/** Where a fixture came from — stamped onto every fixture, honest about synthetic input. */
+export interface FixtureProvenance {
+	readonly bundleSha256: string;
+	/** `true` when the source bundle was synthetic — such a fixture is test data only. */
+	readonly synthetic: boolean;
+	readonly slot: string;
+	readonly capturedAtMs: number;
+}
+
+/** A classifier fixture: the snapshot `classifyDevice` consumes, plus its provenance. */
+export interface ClassifierFixture {
+	readonly snapshot: UsbDeviceSnapshot;
+	readonly provenance: FixtureProvenance;
+}
+
+/** One bundle plus the sha256 `certify` printed for it — the two halves are inseparable. */
+export interface IngestionRequest {
+	/** The bundle JSON, already `JSON.parse`d. Validated here against the view schema. */
+	readonly bundle: unknown;
+	/** The `CERTIFY OK: sha256=…` value. Becomes the entry's `evidenceBundleSha256`. */
+	readonly bundleSha256: string;
+}
+
+/**
+ * The claim a REVIEWER makes about the SKU. `canonicalMode` is stated, never inferred:
+ * a machine reading descriptors could guess it, but a catalog entry is an assertion a
+ * human signs, and a stage-2 bundle's `transition.from` is cross-checked against it.
+ */
+export interface CatalogClaim {
+	readonly canonicalMode: CanonicalUsbMode;
+}
+
+const SHA256_RE = /^[0-9a-f]{64}$/;
+
+/** Validate a request's bundle + sha, or refuse with a precise reason. */
+export function parseIngestionRequest(
+	request: IngestionRequest,
+): IngestionOutcome<EvidenceBundleView> {
+	if (!SHA256_RE.test(request.bundleSha256)) {
+		return refuse(
+			'sha256-malformed',
+			`bundle sha256 must be 64 lowercase hex characters, got '${request.bundleSha256}'`,
+		);
+	}
+	const parsed = evidenceBundleViewSchema.safeParse(request.bundle);
+	if (!parsed.success) {
+		return refuse('bundle-malformed', z.prettifyError(parsed.error));
+	}
+	return { ok: true, value: parsed.data };
+}
+
+/**
+ * Build a classifier test fixture from a bundle — the real udev shape, not a hand-typed
+ * approximation. Descriptors and per-interface DRIVERS come from the bundle's
+ * `usb-devices` text (the only structured descriptor source a base bundle carries);
+ * identity comes from the bundle's SKU; `physicalUid` / `ifname` come from the captured
+ * udev properties. A synthetic bundle is ACCEPTED here and the provenance says so.
+ */
+export function buildClassifierFixture(
+	request: IngestionRequest,
+): IngestionOutcome<ClassifierFixture> {
+	const parsed = parseIngestionRequest(request);
+	if (!parsed.ok) {
+		return parsed;
+	}
+	const bundle = parsed.value;
+	const sku = bundle.sku;
+	if (sku === undefined) {
+		// Blocker B2 in `docs/BENCH.md` produces exactly this: an unmatched USB device
+		// yields a bundle with no SKU at all.
+		return refuse(
+			'sku-missing',
+			'bundle carries no `sku` — the capture did not match a USB device to the slot',
+		);
+	}
+
+	const selected = selectUniqueDevice(parseUsbDevices(bundle.usb.usbDevices), sku.vidPid);
+	if (!('device' in selected)) {
+		return selected.ambiguousMatches === 0
+			? refuse(
+					'device-not-in-capture',
+					`no device with vidPid ${sku.vidPid} in the bundle's usb-devices capture`,
+				)
+			: refuse(
+					'device-ambiguous',
+					`${selected.ambiguousMatches} devices share vidPid ${sku.vidPid} in this capture; a fixture must name one physical device`,
+				);
+	}
+	const device = selected.device;
+	if (device.interfaces.length === 0) {
+		return refuse(
+			'no-interfaces-captured',
+			`device ${sku.vidPid} has no parsed interface lines; a classifier fixture with no interfaces classifies nothing`,
+		);
+	}
+
+	const [vendorId, productId] = sku.vidPid.split(':') as [string, string];
+	const props = bundle.usb.udevProperties;
+	const physicalUid = props.ID_PATH;
+	const ifname = props.INTERFACE;
+
+	return {
+		ok: true,
+		value: {
+			snapshot: {
+				vendorId,
+				productId,
+				model: sku.model,
+				firmwareRevision: sku.firmwarePrefix,
+				bDeviceClass: device.bDeviceClass,
+				interfaces: device.interfaces,
+				udevProperties: props,
+				...(physicalUid !== undefined ? { physicalUid } : {}),
+				...(ifname !== undefined ? { ifname } : {}),
+			},
+			provenance: {
+				bundleSha256: request.bundleSha256,
+				synthetic: bundle.synthetic,
+				slot: bundle.slot,
+				capturedAtMs: bundle.capturedAtMs,
+			},
+		},
+	};
+}
+
+/**
+ * Build a CANDIDATE catalog entry from a bundle. The entry is a review artifact: it is
+ * returned, never written.
+ *
+ * REFUSES a `synthetic: true` bundle — a catalog entry asserts a certified hardware
+ * fact, so synthetic evidence can never back one (`docs/BENCH.md` Must-NOT-Have 7).
+ *
+ * A stage-1 (base) bundle yields `permittedTransitions: []`. A stage-2 bundle — one
+ * captured with `certify --transition` — yields exactly ONE permitted transition, whose
+ * `expectedDescriptors` is the captured `afterDescriptors` and whose
+ * `evidenceBundleSha256` is this bundle's hash. The reviewer's stated `canonicalMode`
+ * must equal the captured `transition.from`; a mismatch is refused rather than silently
+ * resolved in either direction.
+ */
+export function buildCatalogEntryCandidate(
+	request: IngestionRequest,
+	claim: CatalogClaim,
+): IngestionOutcome<CatalogEntry> {
+	const parsed = parseIngestionRequest(request);
+	if (!parsed.ok) {
+		return parsed;
+	}
+	const bundle = parsed.value;
+	if (bundle.synthetic) {
+		return refuse(
+			'synthetic-bundle',
+			`bundle for slot '${bundle.slot}' is marked synthetic:true; a catalog entry requires a real capture (synthetic:false)`,
+		);
+	}
+	const sku = bundle.sku;
+	if (sku === undefined) {
+		return refuse(
+			'sku-missing',
+			'bundle carries no `sku` — a catalog entry needs all three discriminators (vidPid, model, firmwarePrefix)',
+		);
+	}
+
+	const transition = bundle.transition;
+	if (transition !== undefined && transition.from !== claim.canonicalMode) {
+		return refuse(
+			'transition-mode-mismatch',
+			`claimed canonicalMode '${claim.canonicalMode}' contradicts the captured transition.from '${transition.from}'`,
+		);
+	}
+
+	const candidate = {
+		vidPid: sku.vidPid,
+		model: sku.model,
+		firmwarePrefix: sku.firmwarePrefix,
+		canonicalMode: claim.canonicalMode,
+		permittedTransitions:
+			transition === undefined
+				? []
+				: [
+						{
+							from: transition.from,
+							to: transition.to,
+							atCommand: transition.atCommand,
+							expectedResponse: transition.expectedResponse,
+							expectsPortDrop: transition.expectsPortDrop,
+							expectedDescriptors: transition.afterDescriptors,
+							evidenceBundleSha256: request.bundleSha256,
+						},
+					],
+	};
+
+	// The candidate is re-validated through the AUTHORITATIVE entry schema, so an
+	// impossible combination (a router-mode SKU declaring a transition, say) is refused
+	// here rather than at review time.
+	const entry = catalogEntrySchema.safeParse(candidate);
+	if (!entry.success) {
+		return refuse('entry-schema-invalid', z.prettifyError(entry.error));
+	}
+	return { ok: true, value: entry.data };
+}
+
+/** The canonical-mode vocabulary a reviewer's claim may use — re-exported for callers. */
+export const CLAIMABLE_CANONICAL_MODES = CANONICAL_USB_MODES;

package/src/usb-mode/promotion-review.ts

@@ -0,0 +1,117 @@
+// Rendering the REVIEW ARTIFACT for a catalog promotion — the PR-comment template.
+//
+// Catalog additions are human-reviewed commits (Phase-A rule). This module renders what
+// a reviewer reads: the proposed entry, the classifier fixture derived from the same
+// bundle, and a checklist whose boxes a machine cannot tick. It renders a REFUSAL with
+// equal prominence — a refused promotion produces a comment that says so, never silence,
+// because a silently-absent comment is indistinguishable from a forgotten run.
+//
+// Nothing here writes a file or opens a PR. The output is text.
+
+import type { CatalogEntry } from './catalog-schema';
+import type { ClassifierFixture, IngestionOutcome, IngestionRefusal } from './ingestion';
+
+/** Everything the rendered comment needs beyond the two ingestion outcomes. */
+export interface PromotionContext {
+	/** The runbook that captured the bundle (`RB-11` …) — the evidence's provenance. */
+	readonly runbook: string;
+	/** The repo-local evidence path the bundle was written to. */
+	readonly evidencePath: string;
+}
+
+/** A promotion request: the two ingestion outcomes plus where the evidence came from. */
+export interface PromotionRequest {
+	readonly context: PromotionContext;
+	readonly entry: IngestionOutcome<CatalogEntry>;
+	readonly fixture: IngestionOutcome<ClassifierFixture>;
+}
+
+function refusalBlock(what: string, refusal: IngestionRefusal): string {
+	return [
+		`### ❌ ${what} — REFUSED`,
+		'',
+		`**Reason:** \`${refusal.reason}\``,
+		'',
+		`> ${refusal.detail}`,
+		'',
+		'This is a typed refusal from the ingestion seam, not a review opinion. Fix the',
+		'capture and re-run the runbook; do not hand-author the artifact around it.',
+	].join('\n');
+}
+
+function entryBlock(entry: CatalogEntry): string {
+	return [
+		'### Proposed `certified-catalog.json` entry',
+		'',
+		'```json',
+		JSON.stringify(entry, null, 2),
+		'```',
+	].join('\n');
+}
+
+function fixtureBlock(fixture: ClassifierFixture): string {
+	const { snapshot, provenance } = fixture;
+	const syntheticNote = provenance.synthetic
+		? '> ⚠️ Derived from a **synthetic** bundle — valid as test data, never as certification evidence.'
+		: `> Derived from a real capture, bundle sha256 \`${provenance.bundleSha256}\`.`;
+	return [
+		'### Proposed classifier fixture (`control/src/backend/device-classifier.test.ts`)',
+		'',
+		syntheticNote,
+		'',
+		'```ts',
+		`const FIXTURE: UsbDeviceSnapshot = ${JSON.stringify(snapshot, null, 2)};`,
+		'```',
+	].join('\n');
+}
+
+function checklistBlock(context: PromotionContext, entry: CatalogEntry): string {
+	const transitions = entry.permittedTransitions.length;
+	return [
+		'### Reviewer checklist (every box is a human judgement)',
+		'',
+		`- [ ] The bundle at \`${context.evidencePath}\` was captured by **${context.runbook}** on real hardware, and its \`CERTIFY OK\` line reads \`synthetic=false\`.`,
+		'- [ ] The bundle sha256 in the entry matches the sha256 the capture printed — recomputed, not copied from this comment.',
+		`- [ ] \`canonicalMode: "${entry.canonicalMode}"\` is the mode the device was actually observed in, not the mode it was expected to be in.`,
+		transitions === 0
+			? '- [ ] `permittedTransitions: []` is correct for this stage — a stage-1 entry never declares a transition.'
+			: '- [ ] The declared transition was OBSERVED end to end: the AT command executed, the port dropped if `expectsPortDrop`, and the device re-enumerated presenting `expectedDescriptors`.',
+		'- [ ] No claim in `docs/MODEM-SUPPORT-MATRIX.md` is being changed by this commit without its own evidence.',
+	].join('\n');
+}
+
+/**
+ * Render the review comment for a promotion request. Always returns a comment: a
+ * refusal renders a refusal block, so a run that produced nothing promotable still
+ * leaves a visible, auditable trace.
+ */
+export function renderPromotionReview(request: PromotionRequest): string {
+	const { context, entry, fixture } = request;
+	const parts: string[] = [
+		`## Catalog promotion review — ${context.runbook}`,
+		'',
+		`Evidence: \`${context.evidencePath}\``,
+		'',
+		'Generated by the `control/src/usb-mode/` ingestion seam. **This comment promotes',
+		'nothing** — the promotion is the human-reviewed commit that follows it.',
+		'',
+	];
+
+	parts.push(entry.ok ? entryBlock(entry.value) : refusalBlock('Catalog entry', entry));
+	parts.push('');
+	parts.push(
+		fixture.ok ? fixtureBlock(fixture.value) : refusalBlock('Classifier fixture', fixture),
+	);
+	parts.push('');
+	if (entry.ok) {
+		parts.push(checklistBlock(context, entry.value));
+	} else {
+		parts.push(
+			'### No checklist',
+			'',
+			'The catalog entry was refused, so there is nothing to review. A checklist here',
+			'would invite a reviewer to approve an artifact that does not exist.',
+		);
+	}
+	return `${parts.join('\n')}\n`;
+}

package/src/usb-mode/usb-devices-parse.ts

@@ -0,0 +1,196 @@
+// Parsing `usb-devices` text — the ONLY per-interface descriptor source inside a
+// certification bundle.
+//
+// A base certification bundle (`certify <slot>` with no `--transition`) carries no
+// structured descriptors at all: it holds `lsusb -v` and `usb-devices` as raw text plus
+// the slot's udev property map. Authoring a classifier fixture or a catalog entry from
+// such a bundle therefore requires reading the descriptors back out of that text, and
+// `usb-devices` is the right half to read — it is line-oriented, one fixed-width record
+// per device, and it names each interface's BOUND KERNEL DRIVER, which `lsusb -v` does
+// not. The driver is not optional detail here: `classifyDevice` decides `mm-managed` vs
+// `router-mode` partly on `qmi_wwan` / `cdc_ether` / `option` bindings.
+//
+// The parser is pure and total: unparseable lines are SKIPPED, never guessed at, and a
+// device that yields no interfaces still yields a record (callers decide whether an
+// interface-less device is usable — this file never makes that judgement).
+//
+// Record shape (`usb-devices`, one blank-line-separated block per device):
+//   T:  Bus=04 Lev=03 Prnt=03 Port=03 Cnt=01 Dev#=  7 Spd=480 MxCh= 0
+//   D:  Ver= 2.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=64 #Cfgs=  1
+//   P:  Vendor=2c7c ProdID=0801 Rev=05.04
+//   S:  Manufacturer=Quectel
+//   S:  Product=RM530N-GL
+//   I:  If#= 4 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=qmi_wwan
+
+/** One interface line of a `usb-devices` record. */
+export interface ParsedUsbInterface {
+	readonly interfaceClass: number;
+	readonly interfaceSubClass: number;
+	readonly interfaceProtocol: number;
+	/** The bound kernel driver, omitted when `usb-devices` reports `(none)`. */
+	readonly driver?: string;
+}
+
+/** One device block of a `usb-devices` capture. */
+export interface ParsedUsbDevice {
+	/** Lowercase hex `xxxx:xxxx`, exactly the catalog's `vidPid` discriminator shape. */
+	readonly vidPid: string;
+	/** The `D:` line's `Cls=` byte — the device-descriptor `bDeviceClass`. */
+	readonly bDeviceClass: number;
+	readonly manufacturer?: string;
+	readonly product?: string;
+	readonly interfaces: readonly ParsedUsbInterface[];
+}
+
+/** Read `Key=value` from a `usb-devices` line; `undefined` when the key is absent. */
+function field(line: string, key: string): string | undefined {
+	// Values are whitespace-delimited and may be preceded by padding spaces (`Dev#=  7`).
+	// `Cls=ff(vend.)` carries a trailing gloss, stripped by the hex/number parsers below.
+	const match = new RegExp(`${key}=\\s*(\\S+)`).exec(line);
+	return match?.[1];
+}
+
+/** Parse a hex byte field, tolerating `usb-devices`' `ff(vend.)` gloss suffix. */
+function hexByte(line: string, key: string): number | undefined {
+	const raw = field(line, key);
+	if (raw === undefined) {
+		return undefined;
+	}
+	const digits = /^[0-9a-fA-F]{1,2}/.exec(raw)?.[0];
+	if (digits === undefined) {
+		return undefined;
+	}
+	const value = Number.parseInt(digits, 16);
+	return Number.isNaN(value) ? undefined : value;
+}
+
+/** Parse an `S:  Manufacturer=…` style line into its `[key, value]` pair. */
+function stringField(line: string): readonly [string, string] | undefined {
+	const eq = line.indexOf('=');
+	if (eq < 0) {
+		return undefined;
+	}
+	const key = line.slice(3, eq).trim();
+	const value = line.slice(eq + 1).trim();
+	return key === '' || value === '' ? undefined : [key, value];
+}
+
+interface DeviceAccumulator {
+	vidPid?: string;
+	bDeviceClass?: number;
+	manufacturer?: string;
+	product?: string;
+	interfaces: ParsedUsbInterface[];
+}
+
+function emptyAccumulator(): DeviceAccumulator {
+	return { interfaces: [] };
+}
+
+function finish(acc: DeviceAccumulator, out: ParsedUsbDevice[]): void {
+	// A record with no `P:` line is not a device — never synthesise an identity for it.
+	if (acc.vidPid === undefined) {
+		return;
+	}
+	out.push({
+		vidPid: acc.vidPid,
+		bDeviceClass: acc.bDeviceClass ?? 0,
+		interfaces: acc.interfaces,
+		...(acc.manufacturer !== undefined ? { manufacturer: acc.manufacturer } : {}),
+		...(acc.product !== undefined ? { product: acc.product } : {}),
+	});
+}
+
+function applyProductLine(line: string, acc: DeviceAccumulator): void {
+	const vendor = field(line, 'Vendor');
+	const product = field(line, 'ProdID');
+	if (vendor !== undefined && product !== undefined) {
+		acc.vidPid = `${vendor.toLowerCase()}:${product.toLowerCase()}`;
+	}
+}
+
+function applyStringLine(line: string, acc: DeviceAccumulator): void {
+	const pair = stringField(line);
+	if (pair === undefined) {
+		return;
+	}
+	const [key, value] = pair;
+	if (key === 'Manufacturer') {
+		acc.manufacturer = value;
+	} else if (key === 'Product') {
+		acc.product = value;
+	}
+}
+
+function applyInterfaceLine(line: string, acc: DeviceAccumulator): void {
+	const interfaceClass = hexByte(line, 'Cls');
+	const interfaceSubClass = hexByte(line, 'Sub');
+	const interfaceProtocol = hexByte(line, 'Prot');
+	if (
+		interfaceClass === undefined ||
+		interfaceSubClass === undefined ||
+		interfaceProtocol === undefined
+	) {
+		return;
+	}
+	const driver = field(line, 'Driver');
+	acc.interfaces.push({
+		interfaceClass,
+		interfaceSubClass,
+		interfaceProtocol,
+		...(driver !== undefined && driver !== '(none)' ? { driver } : {}),
+	});
+}
+
+/**
+ * Parse `usb-devices` output into one record per device. Pure and total: malformed
+ * lines are skipped rather than guessed at, and a block with no `P:` line yields no
+ * record (it has no identity, so inventing one would be a lie).
+ */
+export function parseUsbDevices(text: string): ParsedUsbDevice[] {
+	const out: ParsedUsbDevice[] = [];
+	let acc = emptyAccumulator();
+	for (const line of text.split('\n')) {
+		// A `T:` line opens a new device record; `usb-devices` also blank-line-separates
+		// them, but the topology line is the reliable delimiter (blank lines are optional
+		// in some kernels' output).
+		if (line.startsWith('T:')) {
+			finish(acc, out);
+			acc = emptyAccumulator();
+			continue;
+		}
+		if (line.startsWith('D:')) {
+			const deviceClass = hexByte(line, 'Cls');
+			if (deviceClass !== undefined) {
+				acc.bDeviceClass = deviceClass;
+			}
+		} else if (line.startsWith('P:')) {
+			applyProductLine(line, acc);
+		} else if (line.startsWith('S:')) {
+			applyStringLine(line, acc);
+		} else if (line.startsWith('I:')) {
+			applyInterfaceLine(line, acc);
+		}
+	}
+	finish(acc, out);
+	return out;
+}
+
+/**
+ * Find the single device matching `vidPid` in a parsed capture. Returns `undefined`
+ * when there is NO match, and — deliberately — also when there is more than one: a
+ * duplicate VID:PID (this bench has two identical Huawei HiLink units) makes the
+ * selection ambiguous, and an ambiguous selection must refuse rather than pick the
+ * first. The caller turns that into a typed refusal.
+ */
+export function selectUniqueDevice(
+	devices: readonly ParsedUsbDevice[],
+	vidPid: string,
+): { readonly device: ParsedUsbDevice } | { readonly ambiguousMatches: number } {
+	const matches = devices.filter((d) => d.vidPid === vidPid);
+	const only = matches[0];
+	if (matches.length === 1 && only !== undefined) {
+		return { device: only };
+	}
+	return { ambiguousMatches: matches.length };
+}