@ceralive/modem-control 1.0.0 → 1.2.0

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,6 @@
+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 { buildRuntimeCompositionSetCommand, isRuntimeCompositionVendor, RUNTIME_COMPOSITION_QUERY_REGISTRY, RUNTIME_COMPOSITION_SET_REGISTRY, RUNTIME_COMPOSITION_VENDORS, type RuntimeCompositionCapability, type RuntimeCompositionMode, type RuntimeCompositionQuery, type RuntimeCompositionResponse, type RuntimeCompositionSetCommand, type RuntimeCompositionVendor, readRuntimeCompositionCurrent, resolveRuntimeCompositionCapability, } from './runtime-capability.js';
+export { type ParsedUsbDevice, type ParsedUsbInterface, parseUsbDevices, selectUniqueDevice, } from './usb-devices-parse.js';

package/dist/usb-mode/index.js

@@ -0,0 +1,16 @@
+// 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 { buildRuntimeCompositionSetCommand, isRuntimeCompositionVendor, RUNTIME_COMPOSITION_QUERY_REGISTRY, RUNTIME_COMPOSITION_SET_REGISTRY, RUNTIME_COMPOSITION_VENDORS, readRuntimeCompositionCurrent, resolveRuntimeCompositionCapability, } from './runtime-capability.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<{
+            "ecm-ncm": "ecm-ncm";
+            mbim: "mbim";
+            qmi: "qmi";
+        }>;
+        to: z.ZodEnum<{
+            "ecm-ncm": "ecm-ncm";
+            mbim: "mbim";
+            qmi: "qmi";
+        }>;
+        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;

package/dist/usb-mode/promotion-review.js

@@ -0,0 +1,87 @@
+// 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.
+function refusalBlock(what, refusal) {
+    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) {
+    return [
+        '### Proposed `certified-catalog.json` entry',
+        '',
+        '```json',
+        JSON.stringify(entry, null, 2),
+        '```',
+    ].join('\n');
+}
+function fixtureBlock(fixture) {
+    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, entry) {
+    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) {
+    const { context, entry, fixture } = request;
+    const parts = [
+        `## 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/dist/usb-mode/runtime-capability.d.ts

@@ -0,0 +1,59 @@
+export declare const RUNTIME_COMPOSITION_VENDORS: readonly ['fibocom', 'quectel', 'simcom', 'sierra'];
+export type RuntimeCompositionVendor = (typeof RUNTIME_COMPOSITION_VENDORS)[number];
+export type RuntimeCompositionMode = number | string;
+export type RuntimeCompositionQuery = {
+    readonly current: string;
+    readonly enumerate: string;
+};
+export type RuntimeCompositionSetCommand = (target: RuntimeCompositionMode) => string | undefined;
+/** Commands only: selecting a port, sending, deadlines, and retries belong to the provider. */
+export declare const RUNTIME_COMPOSITION_QUERY_REGISTRY: Readonly<{
+    fibocom: Readonly<{
+        current: "AT+GTUSBMODE?";
+        enumerate: "AT+GTUSBMODE=?";
+    }>;
+    quectel: Readonly<{
+        current: "AT+QCFG=\"usbnet\"";
+        enumerate: "AT+QCFG=?";
+    }>;
+    simcom: Readonly<{
+        current: "AT+CUSBPIDSWITCH?";
+        enumerate: "AT+CUSBPIDSWITCH=?";
+    }>;
+    sierra: Readonly<{
+        current: "AT!USBCOMP?";
+        enumerate: "AT!USBCOMP=?";
+    }>;
+}>;
+/** Exact reviewed SET forms. Callers still allowlist only the one enumerated target selected. */
+export declare const RUNTIME_COMPOSITION_SET_REGISTRY: Readonly<{
+    fibocom: RuntimeCompositionSetCommand;
+    quectel: RuntimeCompositionSetCommand;
+    simcom: (target: RuntimeCompositionMode) => string | undefined;
+    sierra: RuntimeCompositionSetCommand;
+}>;
+export type RuntimeCompositionCapability = {
+    readonly status: 'available';
+    readonly current: RuntimeCompositionMode;
+    readonly enumerated: readonly RuntimeCompositionMode[];
+    readonly returnPathProven: boolean;
+    readonly offerable: readonly RuntimeCompositionMode[];
+} | {
+    readonly status: 'unknown';
+    readonly current: null;
+    readonly enumerated: readonly [];
+    readonly returnPathProven: false;
+    readonly offerable: readonly [];
+    readonly reason: 'vendor-unsupported' | 'malformed-response';
+};
+export type RuntimeCompositionResponse = {
+    readonly vendor: string;
+    readonly currentResponse: string;
+    readonly enumerationResponse: string;
+};
+export declare function isRuntimeCompositionVendor(vendor: string): vendor is RuntimeCompositionVendor;
+export declare function buildRuntimeCompositionSetCommand(vendor: string, target: RuntimeCompositionMode): string | undefined;
+/** Parse only the vendor READ response used by the weaker post-switch proof tier. */
+export declare function readRuntimeCompositionCurrent(vendor: string, response: string): RuntimeCompositionMode | undefined;
+/** Derive controls exclusively from the device's current and enumerated response text. */
+export declare function resolveRuntimeCompositionCapability(input: RuntimeCompositionResponse): RuntimeCompositionCapability;