@ceralive/modem-control 0.1.0 → 1.0.0

package/src/transport/transport.ts

@@ -1,29 +1,26 @@
 // The D-Bus transport seam implementation.
 //
-// Wraps `@httptoolkit/dbus-native` behind the `DbusTransport` interface: method calls,
-// signal subscriptions, and an automatic reconnect loop that re-issues every match rule
-// after a bus restart. A single persistent `message` listener fans out to the live
-// subscription registry, so subscribing/unsubscribing never grows the connection's
-// listener count — the 100-cycle leak check depends on this.
+// Wraps `@httptoolkit/dbus-native` behind the `DbusTransport` interface. This module owns the
+// connection lifecycle — handshake, a reconnect loop that re-issues every match rule after a
+// bus restart, and teardown — and delegates method-call dispatch to `./calls` and signal
+// subscription/match-rule tracking to `./signals`. Its single `message` listener fans out to
+// the signal registry, so subscribing never grows the listener count (the 100-cycle leak check).
 
 import { EventEmitter } from 'node:events';
-import { decodeBody, encodeBody } from './codec';
+import { CallDispatcher, DEFAULT_CALL_TIMEOUT_MS } from './calls';
 import {
 	type CreateClientOptions,
 	createClient,
-	messageType,
 	type RawBus,
 	type RawMessage,
-	type ReplyContext,
 } from './dbus-native';
 import { DisconnectedError, TransportError } from './errors';
+import { SignalRegistry } from './signals';
 import type {
 	DbusTransport,
 	DbusTransportOptions,
-	DbusValue,
 	MethodCall,
 	MethodReply,
-	SignalEvent,
 	SignalListener,
 	SignalSpec,
 	Subscription,
@@ -39,19 +36,6 @@ interface ResolvedReconnect {
 	readonly maxAttempts: number;
 }
 
-interface SubscriptionRecord {
-	readonly id: number;
-	readonly spec: SignalSpec;
-	readonly listener: SignalListener;
-	readonly rule: string;
-}
-
-interface PendingCall {
-	settle(): void;
-	reject(error: unknown): void;
-}
-
-const DEFAULT_CALL_TIMEOUT_MS = 30_000;
 // Bound a single connect/auth attempt so a stalled handshake cannot freeze the reconnect
 // loop. A local unix-socket D-Bus connect completes in milliseconds; 2s is ample headroom
 // while keeping reconnect responsive after a bus restart.
@@ -65,46 +49,19 @@ const DEFAULT_RECONNECT: ResolvedReconnect = {
 
 const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
 
-function buildMatchRule(spec: SignalSpec): string {
-	const parts = [`type='signal'`, `interface='${spec.interface}'`, `member='${spec.member}'`];
-	if (spec.path !== undefined) {
-		parts.push(`path='${spec.path}'`);
-	}
-	if (spec.sender !== undefined) {
-		parts.push(`sender='${spec.sender}'`);
-	}
-	return parts.join(',');
-}
-
-function signalMatches(spec: SignalSpec, message: RawMessage): boolean {
-	if (message.interface !== spec.interface || message.member !== spec.member) {
-		return false;
-	}
-	if (spec.path !== undefined && message.path !== spec.path) {
-		return false;
-	}
-	if (spec.sender !== undefined && message.sender !== spec.sender) {
-		return false;
-	}
-	return true;
-}
-
 class DbusTransportImpl implements DbusTransport {
 	readonly #options: DbusTransportOptions;
 	readonly #reconnect: ResolvedReconnect;
-	readonly #callTimeoutMs: number;
 	readonly #emitter = new EventEmitter();
-	readonly #subscriptions = new Map<number, SubscriptionRecord>();
-	readonly #matchRuleRefcount = new Map<string, number>();
-	readonly #pending = new Set<PendingCall>();
+	readonly #calls: CallDispatcher;
+	readonly #signals: SignalRegistry;
 
 	#bus: RawBus | null = null;
 	#state: State = 'idle';
 	#closing = false;
-	#nextSubId = 1;
 
 	// Bound once so the same references can be detached from a dead connection.
-	readonly #onMessage = (message: RawMessage): void => this.#dispatchSignal(message);
+	readonly #onMessage = (message: RawMessage): void => this.#signals.dispatch(message);
 	readonly #onConnectionError = (cause: unknown): void =>
 		this.#handleDrop(cause instanceof Error ? cause : new DisconnectedError(String(cause)));
 	readonly #onConnectionEnd = (): void =>
@@ -112,7 +69,12 @@ class DbusTransportImpl implements DbusTransport {
 
 	constructor(options: DbusTransportOptions) {
 		this.#options = options;
-		this.#callTimeoutMs = options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+		this.#calls = new CallDispatcher(options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS);
+		this.#signals = new SignalRegistry({
+			currentBus: () => this.#bus,
+			isConnected: () => this.#state === 'connected',
+			emitError: (error) => this.#emitter.emit('error', error),
+		});
 		this.#reconnect = {
 			enabled: options.reconnect?.enabled ?? DEFAULT_RECONNECT.enabled,
 			initialDelayMs: options.reconnect?.initialDelayMs ?? DEFAULT_RECONNECT.initialDelayMs,
@@ -144,113 +106,23 @@ class DbusTransportImpl implements DbusTransport {
 		this.#state = 'closed';
 		const bus = this.#bus;
 		this.#bus = null;
-		this.#rejectPending(new DisconnectedError('transport closed'));
+		this.#calls.rejectAll(new DisconnectedError('transport closed'));
 		if (bus) {
 			this.#quiesce(bus);
 			await bus.disconnect().catch(() => undefined);
 		}
 	}
 
-	async callMethod(call: MethodCall): Promise<MethodReply> {
-		const bus = this.#bus;
-		if (this.#state !== 'connected' || bus === null) {
-			throw new DisconnectedError('cannot call method: transport not connected');
-		}
-
-		const signature = call.signature ?? '';
-		const args = call.args ?? [];
-		const message: RawMessage = {
-			type: messageType.methodCall,
-			destination: call.destination,
-			path: call.path,
-			interface: call.interface,
-			member: call.member,
-		};
-		if (signature.length > 0) {
-			// Throws UnsupportedSignatureError / BigIntRequiredError before anything hits
-			// the wire.
-			message.signature = signature;
-			message.body = encodeBody(signature, args);
-		}
-
-		const timeoutMs = call.timeoutMs ?? this.#callTimeoutMs;
-		const pendingSet = this.#pending;
-		return new Promise<MethodReply>((resolve, reject) => {
-			let done = false;
-			const pending: PendingCall = {
-				settle: finish,
-				reject: (error) => {
-					finish();
-					reject(error);
-				},
-			};
-
-			function finish(): void {
-				if (done) {
-					return;
-				}
-				done = true;
-				clearTimeout(timer);
-				pendingSet.delete(pending);
-			}
-
-			const timer = setTimeout(() => {
-				finish();
-				reject(
-					new TransportError(
-						`Method call ${call.interface}.${call.member} timed out after ${timeoutMs}ms`,
-					),
-				);
-			}, timeoutMs);
-
-			pendingSet.add(pending);
-
-			bus.invoke(
-				message,
-				function reply(this: ReplyContext, error: unknown, ...body: unknown[]): void {
-					if (done) {
-						// Reply arrived after timeout/disconnect already settled the promise — ignore.
-						return;
-					}
-					finish();
-					if (error) {
-						reject(error instanceof Error ? error : new TransportError(String(error)));
-						return;
-					}
-					try {
-						const replySignature = this.signature ?? '';
-						const decoded: DbusValue[] =
-							replySignature.length > 0 ? decodeBody(replySignature, body) : [];
-						resolve({ signature: replySignature, body: decoded });
-					} catch (decodeError) {
-						reject(decodeError);
-					}
-				},
-			);
-		});
+	callMethod(call: MethodCall): Promise<MethodReply> {
+		return this.#calls.call(this.#bus, this.#state === 'connected', call);
 	}
 
-	async subscribeSignal(spec: SignalSpec, listener: SignalListener): Promise<Subscription> {
-		const rule = buildMatchRule(spec);
-		const id = this.#nextSubId++;
-		this.#subscriptions.set(id, { id, spec, listener, rule });
-		await this.#addMatchRule(rule);
-
-		let removed = false;
-		return {
-			unsubscribe: async (): Promise<void> => {
-				if (removed) {
-					return;
-				}
-				removed = true;
-				this.#subscriptions.delete(id);
-				await this.#removeMatchRule(rule);
-			},
-		};
+	subscribeSignal(spec: SignalSpec, listener: SignalListener): Promise<Subscription> {
+		return this.#signals.subscribe(spec, listener);
 	}
 
 	subscriptionCount(): number {
-		return this.#subscriptions.size;
+		return this.#signals.count();
 	}
 
 	on(event: TransportEvent, handler: (payload?: unknown) => void): void {
@@ -300,9 +172,7 @@ class DbusTransportImpl implements DbusTransport {
 			bus.connection.on('end', this.#onConnectionEnd);
 
 			// Re-issue every live match rule so a reconnect resubscribes transparently.
-			for (const rule of this.#matchRuleRefcount.keys()) {
-				await bus.addMatch(rule);
-			}
+			await this.#signals.reissueRules(bus);
 
 			this.#bus = bus;
 			this.#state = 'connected';
@@ -319,58 +189,6 @@ class DbusTransportImpl implements DbusTransport {
 		}
 	}
 
-	#dispatchSignal(message: RawMessage): void {
-		if (message.type !== messageType.signal) {
-			return;
-		}
-		for (const record of this.#subscriptions.values()) {
-			if (!signalMatches(record.spec, message)) {
-				continue;
-			}
-			let body: DbusValue[];
-			try {
-				const signature = message.signature ?? '';
-				body = signature.length > 0 ? decodeBody(signature, message.body ?? []) : [];
-			} catch (error) {
-				this.#emitter.emit('error', error);
-				continue;
-			}
-			const event: SignalEvent = {
-				path: message.path ?? '',
-				interface: message.interface ?? '',
-				member: message.member ?? '',
-				sender: message.sender,
-				signature: message.signature ?? '',
-				body,
-			};
-			try {
-				record.listener(event);
-			} catch (error) {
-				this.#emitter.emit('error', error);
-			}
-		}
-	}
-
-	async #addMatchRule(rule: string): Promise<void> {
-		const current = this.#matchRuleRefcount.get(rule) ?? 0;
-		this.#matchRuleRefcount.set(rule, current + 1);
-		if (current === 0 && this.#state === 'connected' && this.#bus) {
-			await this.#bus.addMatch(rule);
-		}
-	}
-
-	async #removeMatchRule(rule: string): Promise<void> {
-		const current = this.#matchRuleRefcount.get(rule) ?? 0;
-		if (current <= 1) {
-			this.#matchRuleRefcount.delete(rule);
-			if (current === 1 && this.#state === 'connected' && this.#bus) {
-				await this.#bus.removeMatch(rule).catch(() => undefined);
-			}
-		} else {
-			this.#matchRuleRefcount.set(rule, current - 1);
-		}
-	}
-
 	#detachHandlers(bus: RawBus): void {
 		bus.connection.removeListener('message', this.#onMessage as (...args: unknown[]) => void);
 		bus.connection.removeListener('error', this.#onConnectionError);
@@ -385,13 +203,6 @@ class DbusTransportImpl implements DbusTransport {
 		bus.connection.on('error', () => undefined);
 	}
 
-	#rejectPending(cause: unknown): void {
-		for (const pending of this.#pending) {
-			pending.reject(cause);
-		}
-		this.#pending.clear();
-	}
-
 	#handleDrop(cause: unknown): void {
 		if (this.#closing) {
 			return;
@@ -404,7 +215,7 @@ class DbusTransportImpl implements DbusTransport {
 			this.#quiesce(this.#bus);
 		}
 		this.#bus = null;
-		this.#rejectPending(cause);
+		this.#calls.rejectAll(cause);
 		this.#emitter.emit('disconnected', cause);
 		if (this.#reconnect.enabled) {
 			void this.#reconnectLoop();

package/src/usb-mode/index.ts

@@ -1,8 +1,13 @@
-// The certified USB-mode catalog — schema, data, and lookups.
+// The certified USB-mode catalog — schema, data, lookups, and the evidence-bundle
+// ingestion seam.
 //
 // A6.1's bench CLI (`set-usb-mode`) and A6.2's `certify` tool both consume this: the
 // CLI looks up the permitted transition for a target mode, `certify` validates a
 // candidate entry against the schema before a human commits it.
+//
+// The ingestion seam (`./ingestion`, `./promotion-review`) is the documented path from a
+// captured `certify` bundle to a reviewed catalog commit — see `docs/CATALOG-INGESTION.md`.
+// It refuses a `synthetic: true` bundle for catalog promotion, by construction.
 
 export {
 	CERTIFIED_CATALOG,
@@ -25,3 +30,29 @@ export {
 	permittedTransitionSchema,
 	type SkuDiscriminator,
 } from './catalog-schema';
+export {
+	buildCatalogEntryCandidate,
+	buildClassifierFixture,
+	type CatalogClaim,
+	CLAIMABLE_CANONICAL_MODES,
+	type ClassifierFixture,
+	type EvidenceBundleView,
+	evidenceBundleViewSchema,
+	type FixtureProvenance,
+	type IngestionOutcome,
+	type IngestionRefusal,
+	type IngestionRefusalReason,
+	type IngestionRequest,
+	parseIngestionRequest,
+} from './ingestion';
+export {
+	type PromotionContext,
+	type PromotionRequest,
+	renderPromotionReview,
+} from './promotion-review';
+export {
+	type ParsedUsbDevice,
+	type ParsedUsbInterface,
+	parseUsbDevices,
+	selectUniqueDevice,
+} from './usb-devices-parse';

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');
+	});
+});