@ceralive/modem-control 0.2.0 → 1.0.0

package/src/usb-mode/ingestion.test.ts

@@ -0,0 +1,268 @@
+// The ingestion seam's contract: a bundle round-trips into a schema-valid catalog entry
+// and a real-shaped classifier fixture, the sha256 links the two, and a synthetic bundle
+// is REFUSED for catalog promotion with a typed reason rather than silently accepted.
+
+import { describe, expect, test } from 'bun:test';
+import { classifyDevice, detectUsbMode } from '../backend/device-classifier';
+import { catalogEntrySchema } from './catalog-schema';
+import {
+	buildCatalogEntryCandidate,
+	buildClassifierFixture,
+	type IngestionRequest,
+	parseIngestionRequest,
+} from './ingestion';
+import { renderPromotionReview } from './promotion-review';
+import { parseUsbDevices, selectUniqueDevice } from './usb-devices-parse';
+
+const SHA = 'a'.repeat(64);
+
+/** Verbatim-shaped `usb-devices` output for a QMI stick plus one unrelated hub. */
+const USB_DEVICES = `
+T:  Bus=04 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=5000 MxCh= 4
+D:  Ver= 3.20 Cls=09(hub  ) Sub=00 Prot=03 MxPS= 9 #Cfgs=  1
+P:  Vendor=0bda ProdID=0411 Rev=01.01
+S:  Manufacturer=Generic
+S:  Product=USB3.2 Hub
+I:  If#= 0 Alt= 0 #EPs= 1 Cls=09(hub  ) Sub=00 Prot=00 Driver=hub
+
+T:  Bus=04 Lev=03 Prnt=04 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=0125 Rev=03.18
+S:  Manufacturer=Quectel
+S:  Product=SYNTHETIC-BENCH-STICK
+I:  If#= 2 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=00 Prot=00 Driver=option
+I:  If#= 4 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=qmi_wwan
+`;
+
+function bundle(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+	return {
+		schemaVersion: 1,
+		synthetic: false,
+		capturedAtMs: 1_760_000_000_000,
+		slot: 'Modem/2',
+		sku: {
+			vidPid: '2c7c:0125',
+			model: 'CERALIVE-SYNTHETIC-TEST-SKU',
+			firmwarePrefix: 'SYNTHETICFW01',
+		},
+		usb: {
+			usbDevices: USB_DEVICES,
+			udevProperties: {
+				ID_PATH: 'platform-xhci-hcd.0.auto-usb-0:1.4.4',
+				ID_VENDOR_ID: '2c7c',
+				ID_MODEL_ID: '0125',
+				INTERFACE: 'wwan0',
+			},
+		},
+		// Fields the real bundle carries and the ingestion VIEW deliberately ignores.
+		usbExtra: { lsusb: 'Device Descriptor:' },
+		modemManager: { mmcliKeyfile: {}, managedObjects: {}, signalWindow: [] },
+		...overrides,
+	};
+}
+
+const request = (overrides: Record<string, unknown> = {}, sha = SHA): IngestionRequest => ({
+	bundle: bundle(overrides),
+	bundleSha256: sha,
+});
+
+const TRANSITION = {
+	from: 'qmi',
+	to: 'mbim',
+	atCommand: 'AT+QCFG="usbnet",2',
+	expectedResponse: 'OK',
+	expectsPortDrop: true,
+	afterDescriptors: {
+		deviceClass: 0,
+		interfaces: [
+			{ interfaceClass: 2, interfaceSubClass: 14, interfaceProtocol: 0 },
+			{ interfaceClass: 10, interfaceSubClass: 0, interfaceProtocol: 2 },
+		],
+	},
+	timeline: [{ event: 'command-sent', atMs: 1 }],
+};
+
+describe('parseUsbDevices — the descriptor source a base bundle actually carries', () => {
+	test('parses every device, its bDeviceClass, and each interface driver', () => {
+		const devices = parseUsbDevices(USB_DEVICES);
+		expect(devices).toHaveLength(2);
+		const stick = devices[1];
+		expect(stick?.vidPid).toBe('2c7c:0125');
+		expect(stick?.bDeviceClass).toBe(0);
+		expect(stick?.product).toBe('SYNTHETIC-BENCH-STICK');
+		expect(stick?.interfaces).toEqual([
+			{ interfaceClass: 0xff, interfaceSubClass: 0x00, interfaceProtocol: 0x00, driver: 'option' },
+			{
+				interfaceClass: 0xff,
+				interfaceSubClass: 0xff,
+				interfaceProtocol: 0xff,
+				driver: 'qmi_wwan',
+			},
+		]);
+	});
+
+	test('a block with no P: line yields no record — identity is never invented', () => {
+		expect(parseUsbDevices('T:  Bus=01\nI:  If#= 0 Cls=ff Sub=ff Prot=ff Driver=x')).toEqual([]);
+	});
+
+	test('a duplicate VID:PID is AMBIGUOUS, not first-wins (the Huawei HiLink pair)', () => {
+		const pair = `${USB_DEVICES}\nT:  Bus=01 Lev=01\nD:  Cls=00\nP:  Vendor=2c7c ProdID=0125 Rev=03.18\nI:  If#= 0 Cls=ff Sub=ff Prot=ff Driver=qmi_wwan\n`;
+		const selected = selectUniqueDevice(parseUsbDevices(pair), '2c7c:0125');
+		expect(selected).toEqual({ ambiguousMatches: 2 });
+	});
+});
+
+describe('buildClassifierFixture — the real udev shape, not a hand-typed approximation', () => {
+	test('produces a snapshot the REAL classifier classifies correctly', () => {
+		const outcome = buildClassifierFixture(request());
+		expect(outcome.ok).toBe(true);
+		if (!outcome.ok) {
+			return;
+		}
+		const { snapshot, provenance } = outcome.value;
+		expect(snapshot.vendorId).toBe('2c7c');
+		expect(snapshot.productId).toBe('0125');
+		expect(snapshot.model).toBe('CERALIVE-SYNTHETIC-TEST-SKU');
+		expect(snapshot.firmwareRevision).toBe('SYNTHETICFW01');
+		expect(snapshot.physicalUid).toBe('platform-xhci-hcd.0.auto-usb-0:1.4.4');
+		expect(snapshot.ifname).toBe('wwan0');
+		// The whole point of deriving from real capture text: the fixture must survive
+		// the production classifier, not merely typecheck.
+		expect(classifyDevice(snapshot).deviceClass).toBe('mm-managed');
+		expect(detectUsbMode(snapshot)).toBe('qmi');
+		expect(provenance.bundleSha256).toBe(SHA);
+		expect(provenance.synthetic).toBe(false);
+	});
+
+	test('a SYNTHETIC bundle still yields a fixture, stamped synthetic in provenance', () => {
+		const outcome = buildClassifierFixture(request({ synthetic: true }));
+		expect(outcome.ok).toBe(true);
+		if (outcome.ok) {
+			expect(outcome.value.provenance.synthetic).toBe(true);
+		}
+	});
+
+	test('refuses a bundle with no sku (blocker B2 shape) rather than inventing one', () => {
+		const outcome = buildClassifierFixture(request({ sku: undefined }));
+		expect(outcome).toMatchObject({ ok: false, reason: 'sku-missing' });
+	});
+
+	test('refuses when the SKU is absent from the usb-devices capture', () => {
+		const outcome = buildClassifierFixture(
+			request({ sku: { ...(bundle().sku as object), vidPid: '1199:9071' } }),
+		);
+		expect(outcome).toMatchObject({ ok: false, reason: 'device-not-in-capture' });
+	});
+});
+
+describe('buildCatalogEntryCandidate — schema round-trip and sha linkage', () => {
+	test('a stage-1 bundle yields an entry with NO permitted transitions', () => {
+		const outcome = buildCatalogEntryCandidate(request(), { canonicalMode: 'qmi' });
+		expect(outcome.ok).toBe(true);
+		if (!outcome.ok) {
+			return;
+		}
+		expect(outcome.value.permittedTransitions).toEqual([]);
+		// Round-trip through the AUTHORITATIVE schema, not the builder's own view.
+		expect(catalogEntrySchema.parse(outcome.value)).toEqual(outcome.value);
+	});
+
+	test('a stage-2 bundle links the transition to THIS bundle sha256', () => {
+		const sha = 'b'.repeat(64);
+		const outcome = buildCatalogEntryCandidate(
+			{ bundle: bundle({ transition: TRANSITION }), bundleSha256: sha },
+			{ canonicalMode: 'qmi' },
+		);
+		expect(outcome.ok).toBe(true);
+		if (!outcome.ok) {
+			return;
+		}
+		const [transition] = outcome.value.permittedTransitions;
+		expect(transition?.evidenceBundleSha256).toBe(sha);
+		expect(transition?.expectedDescriptors).toEqual(TRANSITION.afterDescriptors);
+		expect(transition?.atCommand).toBe('AT+QCFG="usbnet",2');
+		expect(catalogEntrySchema.parse(outcome.value)).toEqual(outcome.value);
+	});
+
+	test('REFUSES a synthetic:true bundle for catalog promotion — typed, not silent', () => {
+		const outcome = buildCatalogEntryCandidate(request({ synthetic: true }), {
+			canonicalMode: 'qmi',
+		});
+		expect(outcome.ok).toBe(false);
+		if (outcome.ok) {
+			return;
+		}
+		expect(outcome.reason).toBe('synthetic-bundle');
+		expect(outcome.detail).toContain('synthetic:true');
+	});
+
+	test('refuses a claimed mode that contradicts the captured transition.from', () => {
+		const outcome = buildCatalogEntryCandidate(
+			{ bundle: bundle({ transition: TRANSITION }), bundleSha256: SHA },
+			{ canonicalMode: 'mbim' },
+		);
+		expect(outcome).toMatchObject({ ok: false, reason: 'transition-mode-mismatch' });
+	});
+
+	test('refuses a router-mode SKU that carries a transition (schema invariant)', () => {
+		const outcome = buildCatalogEntryCandidate(
+			{ bundle: bundle({ transition: TRANSITION }), bundleSha256: SHA },
+			{ canonicalMode: 'router-ethernet' },
+		);
+		// The mode cross-check fires first; either refusal is correct, neither is an accept.
+		expect(outcome.ok).toBe(false);
+	});
+
+	test('accepts a router-mode SKU with no transitions (the RB-15 shape)', () => {
+		const outcome = buildCatalogEntryCandidate(request(), { canonicalMode: 'router-ethernet' });
+		expect(outcome.ok).toBe(true);
+		if (outcome.ok) {
+			expect(outcome.value.canonicalMode).toBe('router-ethernet');
+			expect(outcome.value.permittedTransitions).toEqual([]);
+		}
+	});
+
+	test('refuses a malformed sha256 before reading the bundle at all', () => {
+		expect(parseIngestionRequest({ bundle: bundle(), bundleSha256: 'nope' })).toMatchObject({
+			ok: false,
+			reason: 'sha256-malformed',
+		});
+	});
+
+	test('refuses a bundle that fails the view schema', () => {
+		expect(
+			parseIngestionRequest({ bundle: { schemaVersion: 2 }, bundleSha256: SHA }),
+		).toMatchObject({ ok: false, reason: 'bundle-malformed' });
+	});
+});
+
+describe('renderPromotionReview — the review artifact, including for refusals', () => {
+	test('renders the entry, the fixture, and a checklist on success', () => {
+		const req = request();
+		const comment = renderPromotionReview({
+			context: { runbook: 'RB-11', evidencePath: 'test-results/modem-phase-b/08/x/bundle.json' },
+			entry: buildCatalogEntryCandidate(req, { canonicalMode: 'qmi' }),
+			fixture: buildClassifierFixture(req),
+		});
+		expect(comment).toContain('Proposed `certified-catalog.json` entry');
+		expect(comment).toContain('Proposed classifier fixture');
+		expect(comment).toContain('Reviewer checklist');
+		expect(comment).toContain('RB-11');
+		expect(comment).toContain('**This comment promotes');
+	});
+
+	test('a refused promotion renders the refusal and NO checklist', () => {
+		const req = request({ synthetic: true });
+		const comment = renderPromotionReview({
+			context: { runbook: 'RB-11', evidencePath: 'x.json' },
+			entry: buildCatalogEntryCandidate(req, { canonicalMode: 'qmi' }),
+			fixture: buildClassifierFixture(req),
+		});
+		expect(comment).toContain('Catalog entry — REFUSED');
+		expect(comment).toContain('`synthetic-bundle`');
+		expect(comment).toContain('### No checklist');
+		expect(comment).not.toContain('Reviewer checklist');
+		// The fixture half still renders — synthetic fixtures are legitimate test data.
+		expect(comment).toContain('Derived from a **synthetic** bundle');
+	});
+});

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`;
+}