@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/usb-mode/catalog-schema.js

@@ -0,0 +1,97 @@
+// The certified USB-mode catalog schema — the contract that gates a mode switch.
+//
+// A catalog ENTRY is one server-derived SKU discriminator (VID:PID + model +
+// firmware prefix) plus everything a certified transition needs: the canonical mode
+// the SKU speaks, the AT commands that switch it, the expected AT response and
+// port-drop behaviour, the USB descriptors it should present AFTER the switch, and a
+// forward-reference to the evidence bundle that certified it. Certification is a
+// human-reviewed commit that adds an entry — evidence bundles are inputs to that
+// review, never read at runtime.
+//
+// TWO safety invariants are enforced by the SCHEMA ITSELF, not by convention:
+//   1. Permitted transitions are WITHIN-ModemManager only — `qmi ↔ mbim ↔ ecm-ncm`.
+//      A transition's `from`/`to` are typed to the MM-mode enum, so any attempt to
+//      declare an `MM ↔ router` (or `rndis`) transition FAILS to parse.
+//   2. `.strict()` everywhere — an entry carrying an unknown field is rejected, so a
+//      typo or a smuggled extra field can never slip past review as valid data.
+import { z } from 'zod';
+/**
+ * The full canonical USB composition-mode vocabulary. A SKU's `canonicalMode` may be
+ * any of these; only the first three are ModemManager-manageable. (Structurally
+ * identical to `PreferredUsbMode` in the power contract — A4.2 owns this vocabulary.)
+ */
+export const CANONICAL_USB_MODES = ['qmi', 'mbim', 'ecm-ncm', 'rndis', 'router-ethernet'];
+/**
+ * The ModemManager-manageable modes — the ONLY modes a transition may move between.
+ * `rndis` and `router-ethernet` are deliberately absent: a device in either is not
+ * MM-managed, so switching to/from them crosses the MM↔router line the schema forbids.
+ */
+export const MM_USB_MODES = ['qmi', 'mbim', 'ecm-ncm'];
+const canonicalMode = z.enum(CANONICAL_USB_MODES);
+const mmMode = z.enum(MM_USB_MODES);
+/** A `bInterfaceClass`/`bInterfaceSubClass`/`bInterfaceProtocol` byte triple. */
+const usbByte = z.number().int().min(0).max(255);
+/** The USB descriptors a device must present AFTER a transition — the postcondition. */
+export const expectedDescriptorsSchema = z.strictObject({
+    deviceClass: usbByte,
+    interfaces: z
+        .array(z.strictObject({
+        interfaceClass: usbByte,
+        interfaceSubClass: usbByte,
+        interfaceProtocol: usbByte,
+    }))
+        .min(1),
+});
+/** One permitted, certified transition between two MM modes. */
+export const permittedTransitionSchema = z
+    .strictObject({
+    from: mmMode,
+    to: mmMode,
+    /** The EXACT AT command that performs the switch (allowlisted at send time). */
+    atCommand: z.string().min(1),
+    /**
+     * The EXACT AT command that COMMITS the switch on a SKU whose `atCommand` only
+     * writes non-volatile configuration; omitted for a SKU that re-enumerates on
+     * `atCommand` alone. Sent through the SAME allowlisted lease.
+     *
+     * Declaring it is a per-SKU hardware FACT, not a retry. Measured on the bench
+     * RM530N-GL: `AT+QCFG="usbnet",<n>` answers `OK`, reads back the new value, and
+     * leaves the device in the OLD composition for the whole port-drop budget — having
+     * already committed to NV. Undeclared, such a SKU fails on a timeout AFTER it was
+     * silently changed, then lands in the new composition at the next unrelated reboot.
+     */
+    applyCommand: z.string().min(1).optional(),
+    /** The AT response expected on success (e.g. `OK`) — never proof on its own. */
+    expectedResponse: z.string().min(1),
+    /** Whether the control port is expected to drop after the command is written. */
+    expectsPortDrop: z.boolean(),
+    /** The descriptors the device must present after re-enumerating — the postcondition. */
+    expectedDescriptors: expectedDescriptorsSchema,
+    /** sha256 of the evidence bundle that certified this transition (A6.2 fills it). */
+    evidenceBundleSha256: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .optional(),
+})
+    .refine((t) => t.from !== t.to, { message: 'a transition must change mode (from !== to)' });
+/** One certified SKU: its discriminator, canonical mode, and permitted transitions. */
+export const catalogEntrySchema = z
+    .strictObject({
+    /** VID:PID, lowercase hex, `xxxx:xxxx`. */
+    vidPid: z.string().regex(/^[0-9a-f]{4}:[0-9a-f]{4}$/),
+    /** The server-derived model string (a discriminator, not free text). */
+    model: z.string().min(1),
+    /** The firmware-revision prefix that discriminates this personality. */
+    firmwarePrefix: z.string().min(1),
+    /** The mode this SKU speaks as certified. */
+    canonicalMode,
+    /** The certified transitions — empty for a non-MM (router/rndis) SKU. */
+    permittedTransitions: z.array(permittedTransitionSchema),
+})
+    .refine((e) => e.permittedTransitions.length === 0 ||
+    MM_USB_MODES.includes(e.canonicalMode), { message: 'only an MM-mode SKU (qmi/mbim/ecm-ncm) may declare permitted transitions' });
+/** The whole certified catalog file. */
+export const certifiedCatalogSchema = z.strictObject({
+    schemaVersion: z.literal(1),
+    entries: z.array(catalogEntrySchema),
+});

package/dist/usb-mode/catalog.d.ts

@@ -0,0 +1,21 @@
+import { type CatalogEntry, type CertifiedCatalog, type MmUsbMode, type PermittedTransition, type SkuDiscriminator } from './catalog-schema.js';
+/**
+ * Parse and validate an untrusted value as a certified catalog. Throws a `ZodError`
+ * with a precise path if the value violates the schema (unknown field, an MM↔router
+ * transition, a bad VID:PID, etc.).
+ */
+export declare function loadCertifiedCatalog(value: unknown): CertifiedCatalog;
+/** The catalog shipped in this package, validated at module load. */
+export declare const CERTIFIED_CATALOG: CertifiedCatalog;
+/**
+ * Find the catalog entry matching a live device's SKU discriminator. All three
+ * discriminators (VID:PID, model, firmware prefix) must match — a partial match is
+ * NOT a certified device. Returns `undefined` for an uncertified SKU (never a guess).
+ */
+export declare function findCatalogEntry(catalog: CertifiedCatalog, sku: SkuDiscriminator): CatalogEntry | undefined;
+/**
+ * Find the permitted transition `from → to` in a catalog entry. Returns `undefined`
+ * when the entry declares no such transition — the caller MUST treat that as "not
+ * permitted", never as "permitted with no command".
+ */
+export declare function findPermittedTransition(entry: CatalogEntry, from: MmUsbMode, to: MmUsbMode): PermittedTransition | undefined;

package/{src/usb-mode/catalog.ts → dist/usb-mode/catalog.js}

@@ -6,55 +6,33 @@
 // an alternate file (e.g. A6.2's `certify` tool checking a candidate entry) uses
 // `loadCertifiedCatalog`. The evidence bundles the entries reference are NOT read
 // here — only the catalog metadata is.
-
-import {
-	type CatalogEntry,
-	type CertifiedCatalog,
-	certifiedCatalogSchema,
-	type MmUsbMode,
-	type PermittedTransition,
-	type SkuDiscriminator,
-} from './catalog-schema';
+import { certifiedCatalogSchema, } from './catalog-schema.js';
 import rawCatalog from './certified-catalog.json' with { type: 'json' };
-
 /**
  * Parse and validate an untrusted value as a certified catalog. Throws a `ZodError`
  * with a precise path if the value violates the schema (unknown field, an MM↔router
  * transition, a bad VID:PID, etc.).
  */
-export function loadCertifiedCatalog(value: unknown): CertifiedCatalog {
-	return certifiedCatalogSchema.parse(value);
+export function loadCertifiedCatalog(value) {
+    return certifiedCatalogSchema.parse(value);
 }
-
 /** The catalog shipped in this package, validated at module load. */
-export const CERTIFIED_CATALOG: CertifiedCatalog = loadCertifiedCatalog(rawCatalog);
-
+export const CERTIFIED_CATALOG = loadCertifiedCatalog(rawCatalog);
 /**
  * Find the catalog entry matching a live device's SKU discriminator. All three
  * discriminators (VID:PID, model, firmware prefix) must match — a partial match is
  * NOT a certified device. Returns `undefined` for an uncertified SKU (never a guess).
  */
-export function findCatalogEntry(
-	catalog: CertifiedCatalog,
-	sku: SkuDiscriminator,
-): CatalogEntry | undefined {
-	return catalog.entries.find(
-		(entry) =>
-			entry.vidPid === sku.vidPid &&
-			entry.model === sku.model &&
-			entry.firmwarePrefix === sku.firmwarePrefix,
-	);
+export function findCatalogEntry(catalog, sku) {
+    return catalog.entries.find((entry) => entry.vidPid === sku.vidPid &&
+        entry.model === sku.model &&
+        entry.firmwarePrefix === sku.firmwarePrefix);
 }
-
 /**
  * Find the permitted transition `from → to` in a catalog entry. Returns `undefined`
  * when the entry declares no such transition — the caller MUST treat that as "not
  * permitted", never as "permitted with no command".
  */
-export function findPermittedTransition(
-	entry: CatalogEntry,
-	from: MmUsbMode,
-	to: MmUsbMode,
-): PermittedTransition | undefined {
-	return entry.permittedTransitions.find((t) => t.from === from && t.to === to);
+export function findPermittedTransition(entry, from, to) {
+    return entry.permittedTransitions.find((t) => t.from === from && t.to === to);
 }

package/dist/usb-mode/certified-catalog.json

@@ -0,0 +1,67 @@
+{
+    "schemaVersion": 1,
+    "entries": [
+        {
+            "vidPid": "2c7c:0125",
+            "model": "CERALIVE-SYNTHETIC-TEST-SKU",
+            "firmwarePrefix": "SYNTHETICFW01",
+            "canonicalMode": "qmi",
+            "permittedTransitions": [
+                {
+                    "from": "qmi",
+                    "to": "mbim",
+                    "atCommand": "AT+QCFG=\"usbnet\",2",
+                    "expectedResponse": "OK",
+                    "expectsPortDrop": true,
+                    "expectedDescriptors": {
+                        "deviceClass": 0,
+                        "interfaces": [
+                            { "interfaceClass": 2, "interfaceSubClass": 14, "interfaceProtocol": 0 },
+                            { "interfaceClass": 10, "interfaceSubClass": 0, "interfaceProtocol": 2 }
+                        ]
+                    }
+                },
+                {
+                    "from": "mbim",
+                    "to": "qmi",
+                    "atCommand": "AT+QCFG=\"usbnet\",0",
+                    "expectedResponse": "OK",
+                    "expectsPortDrop": true,
+                    "expectedDescriptors": {
+                        "deviceClass": 0,
+                        "interfaces": [
+                            { "interfaceClass": 255, "interfaceSubClass": 255, "interfaceProtocol": 255 }
+                        ]
+                    }
+                },
+                {
+                    "from": "qmi",
+                    "to": "ecm-ncm",
+                    "atCommand": "AT+QCFG=\"usbnet\",1",
+                    "expectedResponse": "OK",
+                    "expectsPortDrop": true,
+                    "expectedDescriptors": {
+                        "deviceClass": 0,
+                        "interfaces": [
+                            { "interfaceClass": 2, "interfaceSubClass": 6, "interfaceProtocol": 0 },
+                            { "interfaceClass": 255, "interfaceSubClass": 255, "interfaceProtocol": 255 }
+                        ]
+                    }
+                },
+                {
+                    "from": "ecm-ncm",
+                    "to": "qmi",
+                    "atCommand": "AT+QCFG=\"usbnet\",0",
+                    "expectedResponse": "OK",
+                    "expectsPortDrop": true,
+                    "expectedDescriptors": {
+                        "deviceClass": 0,
+                        "interfaces": [
+                            { "interfaceClass": 255, "interfaceSubClass": 255, "interfaceProtocol": 255 }
+                        ]
+                    }
+                }
+            ]
+        }
+    ]
+}

package/dist/usb-mode/index.d.ts

@@ -0,0 +1,5 @@
+export { CERTIFIED_CATALOG, findCatalogEntry, findPermittedTransition, loadCertifiedCatalog, } from './catalog.js';
+export { CANONICAL_USB_MODES, type CanonicalUsbMode, type CatalogEntry, type CertifiedCatalog, catalogEntrySchema, certifiedCatalogSchema, type ExpectedDescriptors, expectedDescriptorsSchema, MM_USB_MODES, type MmUsbMode, type PermittedTransition, permittedTransitionSchema, type SkuDiscriminator, } from './catalog-schema.js';
+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.js';
+export { type PromotionContext, type PromotionRequest, renderPromotionReview, } from './promotion-review.js';
+export { type ParsedUsbDevice, type ParsedUsbInterface, parseUsbDevices, selectUniqueDevice, } from './usb-devices-parse.js';

package/dist/usb-mode/index.js

@@ -0,0 +1,15 @@
+// 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, findCatalogEntry, findPermittedTransition, loadCertifiedCatalog, } from './catalog.js';
+export { CANONICAL_USB_MODES, catalogEntrySchema, certifiedCatalogSchema, expectedDescriptorsSchema, MM_USB_MODES, permittedTransitionSchema, } from './catalog-schema.js';
+export { buildCatalogEntryCandidate, buildClassifierFixture, CLAIMABLE_CANONICAL_MODES, evidenceBundleViewSchema, parseIngestionRequest, } from './ingestion.js';
+export { renderPromotionReview, } from './promotion-review.js';
+export { parseUsbDevices, selectUniqueDevice, } from './usb-devices-parse.js';

package/dist/usb-mode/ingestion.d.ts

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import type { UsbDeviceSnapshot } from '../backend/device-classifier.js';
+import { type CanonicalUsbMode, type CatalogEntry } from './catalog-schema.js';
+/** The ingestion VIEW of a certification bundle — non-strict on purpose (see header). */
+export declare const evidenceBundleViewSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    synthetic: z.ZodBoolean;
+    capturedAtMs: z.ZodNumber;
+    slot: z.ZodString;
+    sku: z.ZodOptional<z.ZodObject<{
+        vidPid: z.ZodString;
+        model: z.ZodString;
+        firmwarePrefix: z.ZodString;
+    }, z.core.$strip>>;
+    usb: z.ZodObject<{
+        usbDevices: z.ZodString;
+        udevProperties: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strip>;
+    transition: z.ZodOptional<z.ZodObject<{
+        from: z.ZodEnum<{
+            qmi: "qmi";
+            mbim: "mbim";
+            "ecm-ncm": "ecm-ncm";
+        }>;
+        to: z.ZodEnum<{
+            qmi: "qmi";
+            mbim: "mbim";
+            "ecm-ncm": "ecm-ncm";
+        }>;
+        atCommand: z.ZodString;
+        expectedResponse: z.ZodString;
+        expectsPortDrop: z.ZodBoolean;
+        afterDescriptors: z.ZodObject<{
+            deviceClass: z.ZodNumber;
+            interfaces: z.ZodArray<z.ZodObject<{
+                interfaceClass: z.ZodNumber;
+                interfaceSubClass: z.ZodNumber;
+                interfaceProtocol: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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;
+/** 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;
+}
+/** Validate a request's bundle + sha, or refuse with a precise reason. */
+export declare function parseIngestionRequest(request: IngestionRequest): IngestionOutcome<EvidenceBundleView>;
+/**
+ * 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 declare function buildClassifierFixture(request: IngestionRequest): IngestionOutcome<ClassifierFixture>;
+/**
+ * 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 declare function buildCatalogEntryCandidate(request: IngestionRequest, claim: CatalogClaim): IngestionOutcome<CatalogEntry>;
+/** The canonical-mode vocabulary a reviewer's claim may use — re-exported for callers. */
+export declare const CLAIMABLE_CANONICAL_MODES: readonly ["qmi", "mbim", "ecm-ncm", "rndis", "router-ethernet"];

package/dist/usb-mode/ingestion.js

@@ -0,0 +1,187 @@
+// 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 { CANONICAL_USB_MODES, catalogEntrySchema, expectedDescriptorsSchema, MM_USB_MODES, } from './catalog-schema.js';
+import { parseUsbDevices, selectUniqueDevice } from './usb-devices-parse.js';
+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(),
+});
+const refuse = (reason, detail) => ({
+    ok: false,
+    reason,
+    detail,
+});
+const SHA256_RE = /^[0-9a-f]{64}$/;
+/** Validate a request's bundle + sha, or refuse with a precise reason. */
+export function parseIngestionRequest(request) {
+    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) {
+    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(':');
+    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, claim) {
+    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/dist/usb-mode/promotion-review.d.ts

@@ -0,0 +1,21 @@
+import type { CatalogEntry } from './catalog-schema.js';
+import type { ClassifierFixture, IngestionOutcome } from './ingestion.js';
+/** 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>;
+}
+/**
+ * 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 declare function renderPromotionReview(request: PromotionRequest): string;