@ceralive/modem-control 1.0.0 → 1.1.0

package/dist/providers/registry.js

@@ -0,0 +1,33 @@
+import { DomainError } from '../domain/index.js';
+export class ProviderRegistryError extends DomainError {
+    reason;
+    name = 'ProviderRegistryError';
+    constructor(reason) {
+        super(`provider registration refused: ${reason}`);
+        this.reason = reason;
+    }
+}
+class InMemoryProviderRegistry {
+    /** Startup registration is the registry's documented mutation boundary. */
+    #definitions = [];
+    #revision = 0;
+    get revision() {
+        return this.#revision;
+    }
+    register(definition) {
+        if (this.#definitions.some((candidate) => candidate.id === definition.id)) {
+            throw new ProviderRegistryError('duplicate-provider');
+        }
+        if (definition.profileVersion.trim().length === 0) {
+            throw new ProviderRegistryError('empty-profile-version');
+        }
+        this.#definitions.push(definition);
+        this.#revision += 1;
+    }
+    list() {
+        return [...this.#definitions];
+    }
+}
+export function createProviderRegistry() {
+    return new InMemoryProviderRegistry();
+}

package/dist/providers/ufi-himi/index.d.ts

@@ -0,0 +1,6 @@
+export * from './operations.js';
+export * from './prohibitions.js';
+export * from './provider.js';
+export * from './qualcomm-evidence.js';
+export * from './session.js';
+export * from './transport.js';

package/dist/providers/ufi-himi/index.js

@@ -0,0 +1,6 @@
+export * from './operations.js';
+export * from './prohibitions.js';
+export * from './provider.js';
+export * from './qualcomm-evidence.js';
+export * from './session.js';
+export * from './transport.js';

package/dist/providers/ufi-himi/operations.d.ts

@@ -0,0 +1,41 @@
+import { type OperationDescriptor, type OperationResult } from '../../domain/index.js';
+import type { ProviderReadOperations } from '../contracts.js';
+import { type UfiProhibitionClass, type UfiProhibitionReason } from './prohibitions.js';
+export declare const UFI_PROFILE = "ufi-himi-read-only";
+/** The reason every descriptor gives for its absent write half. One string, one meaning. */
+export declare const UFI_READ_ONLY_REASON = "ufi-himi-provider-is-read-only";
+export type UfiReadValue = Readonly<Record<string, unknown>>;
+/**
+ * `ProviderReadOperations` is used verbatim rather than a local shape, because it has no
+ * `write` member to omit — the absence is structural, not a convention this file keeps.
+ */
+export type UfiReadOperation = ProviderReadOperations<UfiReadValue>;
+export declare const UFI_READ_OPERATION_IDS: readonly ["ufi.signal.read", "ufi.details.read"];
+export type UfiReadOperationId = (typeof UFI_READ_OPERATION_IDS)[number];
+export declare function isUfiReadOperation(operationId: string): operationId is UfiReadOperationId;
+export declare function ufiReadDescriptor(operationId: UfiReadOperationId): OperationDescriptor<never, UfiReadValue>;
+export declare function ufiReadResult(generation: OperationResult<UfiReadValue>['generation'], value: UfiReadValue): OperationResult<UfiReadValue>;
+export declare function ufiRefusedResult(generation: OperationResult<UfiReadValue>['generation'], reason: string): OperationResult<UfiReadValue>;
+export type UfiOperationPlan = {
+    readonly status: 'read';
+    readonly operationId: UfiReadOperationId;
+} | {
+    readonly status: 'refused';
+    readonly operationId: string;
+    readonly reason: UfiProhibitionReason | 'unknown-operation';
+    readonly prohibitionClass: UfiProhibitionClass | null;
+    /**
+     * A literal, and provable: this function takes no transport, holds no session,
+     * and returns synchronously — there is nothing here that could reach the device.
+     */
+    readonly transportContacted: false;
+};
+/**
+ * Resolve an operation id BEFORE anything is dialled.
+ *
+ * Prohibited ids are answered from the frozen table first, so a forbidden operation is
+ * never mistaken for a typo. An id that is neither prohibited nor a known read is
+ * `unknown-operation` — also refused, because a read-only provider's operation set is
+ * closed and "not in the set" is a complete answer.
+ */
+export declare function planUfiOperation(operationId: string): UfiOperationPlan;

package/dist/providers/ufi-himi/operations.js

@@ -0,0 +1,66 @@
+import { defineOperationDescriptor, } from '../../domain/index.js';
+import { ufiProhibition, } from './prohibitions.js';
+export const UFI_PROFILE = 'ufi-himi-read-only';
+/** The reason every descriptor gives for its absent write half. One string, one meaning. */
+export const UFI_READ_ONLY_REASON = 'ufi-himi-provider-is-read-only';
+export const UFI_READ_OPERATION_IDS = ['ufi.signal.read', 'ufi.details.read'];
+export function isUfiReadOperation(operationId) {
+    return UFI_READ_OPERATION_IDS.includes(operationId);
+}
+export function ufiReadDescriptor(operationId) {
+    return defineOperationDescriptor({
+        id: operationId,
+        support: {
+            read: { supported: true },
+            write: { supported: false, reason: UFI_READ_ONLY_REASON },
+        },
+        authority: 'provider',
+        provider: 'ufi-himi',
+        constraints: { kind: 'unconstrained' },
+        livePreconditions: ['ufi-himi-session'],
+        availability: { state: 'available' },
+        mutationImpact: 'read',
+        retryClass: 'idempotent-read',
+        readback: { required: false },
+        rollback: { required: false },
+        journal: { required: false },
+        admission: { required: false },
+        evidence: { profiles: [UFI_PROFILE], firmware: [] },
+        confidence: 'medium',
+    });
+}
+export function ufiReadResult(generation, value) {
+    return { status: 'applied', value, generation, requiresReconciliation: false };
+}
+export function ufiRefusedResult(generation, reason) {
+    return { status: 'refused', reason, generation, requiresReconciliation: false };
+}
+/**
+ * Resolve an operation id BEFORE anything is dialled.
+ *
+ * Prohibited ids are answered from the frozen table first, so a forbidden operation is
+ * never mistaken for a typo. An id that is neither prohibited nor a known read is
+ * `unknown-operation` — also refused, because a read-only provider's operation set is
+ * closed and "not in the set" is a complete answer.
+ */
+export function planUfiOperation(operationId) {
+    const prohibition = ufiProhibition(operationId);
+    if (prohibition !== undefined) {
+        return {
+            status: 'refused',
+            operationId,
+            reason: prohibition.reason,
+            prohibitionClass: prohibition.class,
+            transportContacted: false,
+        };
+    }
+    if (isUfiReadOperation(operationId))
+        return { status: 'read', operationId };
+    return {
+        status: 'refused',
+        operationId,
+        reason: 'unknown-operation',
+        prohibitionClass: null,
+        transportContacted: false,
+    };
+}

package/dist/providers/ufi-himi/prohibitions.d.ts

@@ -0,0 +1,62 @@
+import { type OperationDescriptor } from '../../domain/index.js';
+export type UfiProhibitionClass = 'device-integrity' | 'firmware' | 'recovery-automation' | 'diagnostic-channel' | 'transport-fallback';
+export declare const UFI_PROHIBITED_OPERATIONS: {
+    readonly 'nv.write': {
+        readonly reason: "nv-write-prohibited";
+        readonly class: "device-integrity";
+    };
+    readonly 'efs.write': {
+        readonly reason: "efs-write-prohibited";
+        readonly class: "device-integrity";
+    };
+    readonly 'identity.write': {
+        readonly reason: "identity-write-prohibited";
+        readonly class: "device-integrity";
+    };
+    readonly 'calibration.write': {
+        readonly reason: "calibration-write-prohibited";
+        readonly class: "device-integrity";
+    };
+    readonly 'firmware.flash': {
+        readonly reason: "firmware-flash-prohibited";
+        readonly class: "firmware";
+    };
+    readonly 'edl.automation': {
+        readonly reason: "edl-automation-prohibited";
+        readonly class: "recovery-automation";
+    };
+    readonly 'driver.blind-retry': {
+        readonly reason: "blind-driver-retry-prohibited";
+        readonly class: "recovery-automation";
+    };
+    readonly 'interface.blind-retry': {
+        readonly reason: "blind-interface-retry-prohibited";
+        readonly class: "recovery-automation";
+    };
+    readonly 'diag.write': {
+        readonly reason: "diag-write-prohibited";
+        readonly class: "diagnostic-channel";
+    };
+    readonly 'diag.info-probe': {
+        readonly reason: "diag-probe-is-bench-supervised-only";
+        readonly class: "diagnostic-channel";
+    };
+    readonly 'shell.transport-fallback': {
+        readonly reason: "shell-transport-fallback-prohibited";
+        readonly class: "transport-fallback";
+    };
+};
+export type UfiProhibitedOperationId = keyof typeof UFI_PROHIBITED_OPERATIONS;
+export type UfiProhibition = (typeof UFI_PROHIBITED_OPERATIONS)[UfiProhibitedOperationId];
+export type UfiProhibitionReason = UfiProhibition['reason'];
+export declare const UFI_PROHIBITED_OPERATION_IDS: readonly UfiProhibitedOperationId[];
+export declare function isUfiProhibitedOperation(operationId: string): operationId is UfiProhibitedOperationId;
+export declare function ufiProhibition(operationId: string): UfiProhibition | undefined;
+/**
+ * An INERT descriptor, so the same refusal survives a trip through the operation engine.
+ *
+ * It declares read AND write unsupported and availability refused, and it constrains
+ * inputs to the empty set — three independent fences, each sufficient on its own. It
+ * carries no execute/readback/rollback function because none exists to carry.
+ */
+export declare function ufiProhibitionDescriptor(operationId: UfiProhibitedOperationId): OperationDescriptor<unknown, never>;

package/dist/providers/ufi-himi/prohibitions.js

@@ -0,0 +1,88 @@
+// The Qualcomm/HIMI prohibition table.
+//
+// These operations have NO IMPLEMENTATION ANYWHERE in this provider — not a refused
+// stub, not a disabled branch, not a private helper. The table below is inert DATA: it
+// exists so a caller asking for one of these ids gets a NAMED refusal instead of an
+// "unknown operation" shrug, and so the fence can be enumerated by a test rather than
+// argued for in prose. Nothing here can perform anything.
+//
+// Why each is prohibited rather than merely gated:
+//
+//   NV / EFS / identity / calibration writes — they rewrite the modem's own persistent
+//     storage. A bad write bricks the radio, forges an IMEI, or destroys the factory RF
+//     calibration, and none of the three is recoverable from this device's userspace.
+//     Identity writes are additionally illegal in most jurisdictions.
+//   Firmware flashing and EDL automation — an interrupted flash leaves a device that
+//     enumerates only in emergency-download mode, which needs physical access this
+//     controller by definition does not have on a deployed board.
+//   Blind driver / interface retries — re-binding a driver or cycling an interface
+//     "until it works" is how a transient enumeration fault becomes a reboot loop, and
+//     it destroys the evidence the next diagnosis needs.
+//   DIAG writes — the Qualcomm DIAG channel can reach every one of the above.
+//   The DIAG info probe — READ-only and legitimate, but bench-only and human-supervised
+//     (docs/UFI-DIAG-PROBE.md). It is not a production operation and never becomes one.
+//   Shell transport fallback — production never reaches this device over ADB, SSH,
+//     telnet or DIAG under any circumstance. The HIMI HTTP API is the only transport.
+import { defineOperationDescriptor } from '../../domain/index.js';
+export const UFI_PROHIBITED_OPERATIONS = {
+    'nv.write': { reason: 'nv-write-prohibited', class: 'device-integrity' },
+    'efs.write': { reason: 'efs-write-prohibited', class: 'device-integrity' },
+    'identity.write': { reason: 'identity-write-prohibited', class: 'device-integrity' },
+    'calibration.write': { reason: 'calibration-write-prohibited', class: 'device-integrity' },
+    'firmware.flash': { reason: 'firmware-flash-prohibited', class: 'firmware' },
+    'edl.automation': { reason: 'edl-automation-prohibited', class: 'recovery-automation' },
+    'driver.blind-retry': { reason: 'blind-driver-retry-prohibited', class: 'recovery-automation' },
+    'interface.blind-retry': {
+        reason: 'blind-interface-retry-prohibited',
+        class: 'recovery-automation',
+    },
+    'diag.write': { reason: 'diag-write-prohibited', class: 'diagnostic-channel' },
+    'diag.info-probe': {
+        reason: 'diag-probe-is-bench-supervised-only',
+        class: 'diagnostic-channel',
+    },
+    'shell.transport-fallback': {
+        reason: 'shell-transport-fallback-prohibited',
+        class: 'transport-fallback',
+    },
+};
+export const UFI_PROHIBITED_OPERATION_IDS = Object.keys(UFI_PROHIBITED_OPERATIONS);
+export function isUfiProhibitedOperation(operationId) {
+    return Object.hasOwn(UFI_PROHIBITED_OPERATIONS, operationId);
+}
+export function ufiProhibition(operationId) {
+    return isUfiProhibitedOperation(operationId) ? UFI_PROHIBITED_OPERATIONS[operationId] : undefined;
+}
+/**
+ * An INERT descriptor, so the same refusal survives a trip through the operation engine.
+ *
+ * It declares read AND write unsupported and availability refused, and it constrains
+ * inputs to the empty set — three independent fences, each sufficient on its own. It
+ * carries no execute/readback/rollback function because none exists to carry.
+ */
+export function ufiProhibitionDescriptor(operationId) {
+    const { reason } = UFI_PROHIBITED_OPERATIONS[operationId];
+    return defineOperationDescriptor({
+        id: operationId,
+        support: {
+            read: { supported: false, reason },
+            write: { supported: false, reason },
+        },
+        authority: 'provider',
+        provider: 'ufi-himi',
+        constraints: { kind: 'allowed-values', values: [] },
+        livePreconditions: [],
+        availability: { state: 'refused', reason },
+        // `disruptive`, not `write`: every one of these rewrites persistent device state
+        // or drives a recovery mode. The engine treats any non-read impact as a write
+        // (queued behind the modem's actor), so the refusal path is identical.
+        mutationImpact: 'disruptive',
+        retryClass: 'never',
+        readback: { required: false },
+        rollback: { required: false },
+        journal: { required: false },
+        admission: { required: false },
+        evidence: { profiles: [], firmware: [] },
+        confidence: 'high',
+    });
+}

package/dist/providers/ufi-himi/provider.d.ts

@@ -0,0 +1,41 @@
+import type { ObservationEnvelope } from '../../domain/index.js';
+import type { NormalizedModemObservation } from '../../observations/index.js';
+import type { CapabilityReader, ProviderDefinition, ProviderExecutionContext, ProviderMatchRequest, ProviderOperationsSurface } from '../contracts.js';
+import { type UfiOperationPlan, type UfiReadOperation } from './operations.js';
+import { type UfiProhibitedOperationId } from './prohibitions.js';
+import { UFI_DIAG_PRODUCTION_ACCESS } from './qualcomm-evidence.js';
+import { type UfiOptions, UfiSessionRuntime } from './session.js';
+export type { UfiOptions } from './session.js';
+export type UfiOperationsSurface = ProviderOperationsSurface & {
+    readonly access: 'read-only';
+    readonly reads: readonly UfiReadOperation[];
+    readonly prohibited: readonly UfiProhibitedOperationId[];
+    readonly diagAccess: typeof UFI_DIAG_PRODUCTION_ACCESS;
+    readonly plan: (operationId: string) => UfiOperationPlan;
+};
+export declare class UfiHimiProvider extends UfiSessionRuntime {
+    fingerprint(request: ProviderMatchRequest): Promise<{
+        signal: "unknown";
+        strength: "strong";
+        profiles: readonly string[];
+        detail: string;
+    } | {
+        signal: "unknown" | "match";
+        strength: "strong";
+        profiles: string[];
+        detail: string;
+    }>;
+    capability(): CapabilityReader;
+    observe(context: ProviderExecutionContext): Promise<readonly ObservationEnvelope<NormalizedModemObservation>[]>;
+    operations(_profile: string): UfiOperationsSurface;
+    private readSignal;
+    private readDetails;
+    private usbEvidencePermitsProbe;
+    /**
+     * Reads are issued sequentially on ONE session. A `SessionOut` in any body drops the
+     * cached session so the NEXT generation may spend its own single login; it never
+     * re-authenticates inside this cycle.
+     */
+    private fetch;
+}
+export declare function createUfiHimiDefinition(options: UfiOptions): ProviderDefinition<NormalizedModemObservation, UfiOperationsSurface>;

package/dist/providers/ufi-himi/provider.js

@@ -0,0 +1,204 @@
+// Qualcomm UFI / HIMI — a READ-ONLY provider, by construction rather than by policy.
+//
+// This provider normalizes the telemetry the pure parsers already own
+// (`hardware/router-parsers.ts` → `observations/sources/ufi.ts`, migrated in todo 17).
+// It adds a session and a transport around them and nothing else: there is no write
+// descriptor, no write command in the transport vocabulary, and no operation id outside
+// the closed read set that resolves to anything but a typed refusal.
+//
+// The Qualcomm safety model it encodes lives in two neighbouring modules —
+// `qualcomm-evidence.ts` (what a USB id proves) and `prohibitions.ts` (what may never be
+// attempted). Both are inert data; neither can act.
+import { epochMillis, sourceEpoch, stableKeyFromPhysicalModemId } from '../../domain/index.js';
+import { parseUfiDetails, parseUfiSignal } from '../../hardware/router-parsers.js';
+import { normalizeUfiObservation } from '../../observations/sources/ufi.js';
+import { planUfiOperation, UFI_PROFILE, ufiReadDescriptor, ufiReadResult, ufiRefusedResult, } from './operations.js';
+import { UFI_PROHIBITED_OPERATION_IDS } from './prohibitions.js';
+import { UFI_DIAG_PRODUCTION_ACCESS, UFI_MATCHED_USB_IDS } from './qualcomm-evidence.js';
+import { parseUfiReply, UFI_SESSION_REFUSAL, UfiSessionRuntime } from './session.js';
+import { UFI_API_PATH } from './transport.js';
+export class UfiHimiProvider extends UfiSessionRuntime {
+    async fingerprint(request) {
+        // The HIMI fingerprint needs a SESSION to read anything, so this probe is the one
+        // place a "harmless unauthenticated probe" would spend the provider's single
+        // bounded login. On a device that enumerated a USB id and it is not a HIMI id,
+        // that login would be aimed at somebody else's dongle — a credential attempt
+        // against hardware this provider has positive evidence it does not own. An
+        // ABSENT usb fact is still probed (nobody enumerated one; that is not a denial).
+        if (!this.usbEvidencePermitsProbe(request)) {
+            return {
+                signal: 'unknown',
+                strength: 'strong',
+                profiles: [],
+                detail: 'usb-id-is-not-himi',
+            };
+        }
+        const bodies = await this.fetch(request, ['getallstatus']);
+        const reply = parseUfiReply(bodies?.getallstatus ?? '');
+        const matched = reply?.reply === 'ok' && reply.params !== undefined;
+        return {
+            signal: matched ? 'match' : 'unknown',
+            strength: 'strong',
+            profiles: matched ? [UFI_PROFILE] : [],
+            detail: matched ? 'himi-json-shape' : 'himi-json-not-proven',
+        };
+    }
+    capability() {
+        return {
+            id: 'ufi-himi-telemetry',
+            read: async (context) => {
+                const bodies = await this.fetch(context, ['getsysinfo']);
+                const reply = parseUfiReply(bodies?.getsysinfo ?? '');
+                const supported = reply?.reply === 'ok' && reply.params !== undefined;
+                return {
+                    signal: supported ? 'match' : 'mismatch',
+                    strength: 'strong',
+                    detail: supported ? 'telemetry-reported' : 'telemetry-refused',
+                };
+            },
+        };
+    }
+    async observe(context) {
+        const bodies = await this.fetch(context, [
+            'getsysinfo',
+            'getoverview',
+            'getallstatus',
+            'getproduceinfo',
+        ]);
+        if (bodies === undefined)
+            return [];
+        const produceInfo = bodies.getproduceinfo;
+        return [
+            normalizeUfiObservation({
+                sysinfo: bodies.getsysinfo ?? '',
+                overview: bodies.getoverview ?? '',
+                status: bodies.getallstatus ?? '',
+                ...(produceInfo === undefined ? {} : { produceInfo }),
+            }, {
+                stableKey: stableKeyFromPhysicalModemId(context.physicalModemId),
+                generation: context.generation,
+                sourceEpoch: sourceEpoch(1),
+                observedAt: epochMillis(this.observedAt()),
+            }),
+        ];
+    }
+    operations(_profile) {
+        return {
+            access: 'read-only',
+            reads: [
+                {
+                    descriptor: ufiReadDescriptor('ufi.signal.read'),
+                    read: (context) => this.readSignal(context),
+                },
+                {
+                    descriptor: ufiReadDescriptor('ufi.details.read'),
+                    read: (context) => this.readDetails(context),
+                },
+            ],
+            prohibited: UFI_PROHIBITED_OPERATION_IDS,
+            diagAccess: UFI_DIAG_PRODUCTION_ACCESS,
+            plan: planUfiOperation,
+        };
+    }
+    async readSignal(context) {
+        const bodies = await this.fetch(context, ['getsysinfo', 'getoverview', 'getallstatus']);
+        if (bodies === undefined)
+            return ufiRefusedResult(context.generation, 'session-unavailable');
+        const value = parseUfiSignal({
+            sysinfo: bodies.getsysinfo ?? '',
+            overview: bodies.getoverview ?? '',
+            status: bodies.getallstatus ?? '',
+        });
+        return ufiReadResult(context.generation, value);
+    }
+    async readDetails(context) {
+        const bodies = await this.fetch(context, ['getoverview', 'getsysinfo', 'getproduceinfo']);
+        if (bodies === undefined)
+            return ufiRefusedResult(context.generation, 'session-unavailable');
+        const details = parseUfiDetails({
+            overview: bodies.getoverview ?? '',
+            sysinfo: bodies.getsysinfo ?? '',
+            produceInfo: bodies.getproduceinfo ?? '',
+        });
+        return details === undefined
+            ? ufiRefusedResult(context.generation, 'not-reported')
+            : ufiReadResult(context.generation, details);
+    }
+    usbEvidencePermitsProbe(request) {
+        const enumerated = request.passiveFacts.filter((fact) => fact.kind === 'usb');
+        return (enumerated.length === 0 ||
+            enumerated.some((fact) => UFI_MATCHED_USB_IDS.some((id) => id === fact.value)));
+    }
+    /**
+     * Reads are issued sequentially on ONE session. A `SessionOut` in any body drops the
+     * cached session so the NEXT generation may spend its own single login; it never
+     * re-authenticates inside this cycle.
+     */
+    async fetch(request, commands) {
+        const session = await this.session(request);
+        if (session === undefined)
+            return undefined;
+        const bodies = {};
+        for (const command of commands) {
+            const response = await this.read(command, session);
+            bodies[command] = response.status === 200 ? response.body : '';
+        }
+        const refused = Object.values(bodies).some((body) => parseUfiReply(body)?.reply === UFI_SESSION_REFUSAL);
+        if (refused)
+            this.forgetSession(request);
+        return bodies;
+    }
+}
+export function createUfiHimiDefinition(options) {
+    const runtime = new UfiHimiProvider(options);
+    return {
+        id: 'ufi-himi',
+        profileVersion: '1',
+        eligibleTransports: ['network'],
+        passiveMatchers: [
+            {
+                // ONE matcher over both ids. `9024` is the RNDIS+ADB composition and `9091` is
+                // a firmware-chosen product id; both identify a HIMI stick, and NEITHER is
+                // evidence of a DIAG channel (see qualcomm-evidence.ts).
+                id: 'usb-qualcomm-himi',
+                fact: 'usb',
+                expected: UFI_MATCHED_USB_IDS,
+                profiles: [UFI_PROFILE],
+                strength: 'strong',
+                required: true,
+            },
+        ],
+        unauthenticatedProbes: [
+            { id: 'ufi-himi-shape', run: (request) => runtime.fingerprint(request) },
+        ],
+        capabilityReaders: [runtime.capability()],
+        observe: (context) => runtime.observe(context),
+        operations: (profile) => runtime.operations(profile),
+        contractFixtures: [
+            {
+                profile: UFI_PROFILE,
+                request: {
+                    method: 'POST',
+                    path: UFI_API_PATH,
+                    cmdid: 'login',
+                    credentials: '[redacted]',
+                    interfaceBound: true,
+                    redirects: 'disabled',
+                },
+                response: { reply: 'ok', session: '[redacted]' },
+            },
+            {
+                profile: UFI_PROFILE,
+                request: {
+                    method: 'POST',
+                    path: UFI_API_PATH,
+                    cmdid: 'getsysinfo',
+                    authorization: '[redacted]',
+                    interfaceBound: true,
+                    redirects: 'disabled',
+                },
+                response: { reply: 'ok', params: '[verbatim-diagnostics]' },
+            },
+        ],
+    };
+}

package/dist/providers/ufi-himi/qualcomm-evidence.d.ts

@@ -0,0 +1,32 @@
+export declare const UFI_RNDIS_ADB_USB_ID = "05c6:9024";
+export declare const UFI_FIRMWARE_SPECIFIC_USB_ID = "05c6:9091";
+export type UfiUsbClaim = 'rndis-network' | 'adb-interface';
+export declare const UFI_USB_EVIDENCE: {
+    readonly "05c6:9024": readonly ["rndis-network", "adb-interface"];
+    /** Deliberately empty: a firmware-chosen product id claims nothing by itself. */
+    readonly "05c6:9091": readonly [];
+};
+export declare const UFI_MATCHED_USB_IDS: readonly ["05c6:9024", "05c6:9091"];
+export declare function ufiUsbClaims(usbId: string): readonly UfiUsbClaim[];
+export type UfiUsbInterfaceDescriptor = {
+    readonly number: number;
+    readonly interfaceClass: number;
+    readonly interfaceSubClass: number;
+    readonly interfaceProtocol: number;
+};
+export type UfiDiagEvidence = {
+    readonly state: 'descriptor-confirmed';
+    readonly interfaceNumber: number;
+} | {
+    readonly state: 'not-proven';
+    readonly reason: 'product-id-is-not-evidence' | 'no-diag-interface-descriptor';
+};
+export declare function classifyUfiDiagEvidence(input: {
+    readonly usbId: string;
+    readonly interfaces: readonly UfiUsbInterfaceDescriptor[];
+}): UfiDiagEvidence;
+/**
+ * Unconditional. A descriptor-confirmed DIAG channel raises what a SUPERVISED BENCH
+ * operator may attempt by hand; it never raises what this package may do on its own.
+ */
+export declare const UFI_DIAG_PRODUCTION_ACCESS: "prohibited";

package/dist/providers/ufi-himi/qualcomm-evidence.js

@@ -0,0 +1,51 @@
+// What a Qualcomm USB id does and does not prove.
+//
+// `05c6:9024` is the composition the bench UFI sticks enumerate in: RNDIS networking
+// plus an ADB interface. That is EVIDENCE OF A COMPOSITION, not a permission — the ADB
+// interface being present is exactly why production must be explicit that it never uses
+// it (see `shell.transport-fallback` in prohibitions.ts).
+//
+// `05c6:9091` is a FIRMWARE-SPECIFIC product id. It is routinely read as "DIAG is
+// available", and that reading is wrong: `05c6` is Qualcomm's generic vendor id and the
+// product id is chosen by whoever built the firmware image, so it says nothing about
+// which interfaces the device actually exposes. Treating it as proof of DIAG is how a
+// tool ends up opening a channel that is not there, or worse, one that is there and
+// belongs to something else.
+//
+// The only thing that proves a DIAG channel is a DIAG INTERFACE DESCRIPTOR. And even a
+// confirmed one buys nothing in production: `UFI_DIAG_PRODUCTION_ACCESS` is `prohibited`
+// unconditionally, and the supervised read-only info probe is a bench runbook
+// (docs/UFI-DIAG-PROBE.md), never an operation this package can perform.
+export const UFI_RNDIS_ADB_USB_ID = '05c6:9024';
+export const UFI_FIRMWARE_SPECIFIC_USB_ID = '05c6:9091';
+export const UFI_USB_EVIDENCE = {
+    [UFI_RNDIS_ADB_USB_ID]: ['rndis-network', 'adb-interface'],
+    /** Deliberately empty: a firmware-chosen product id claims nothing by itself. */
+    [UFI_FIRMWARE_SPECIFIC_USB_ID]: [],
+};
+export const UFI_MATCHED_USB_IDS = [UFI_RNDIS_ADB_USB_ID, UFI_FIRMWARE_SPECIFIC_USB_ID];
+export function ufiUsbClaims(usbId) {
+    return Object.hasOwn(UFI_USB_EVIDENCE, usbId)
+        ? UFI_USB_EVIDENCE[usbId]
+        : [];
+}
+/** Qualcomm's DIAG interface: vendor-specific class/subclass with protocol 0x30. */
+const DIAG_INTERFACE_CLASS = 0xff;
+const DIAG_INTERFACE_SUBCLASS = 0xff;
+const DIAG_INTERFACE_PROTOCOL = 0x30;
+export function classifyUfiDiagEvidence(input) {
+    const diag = input.interfaces.find((descriptor) => descriptor.interfaceClass === DIAG_INTERFACE_CLASS &&
+        descriptor.interfaceSubClass === DIAG_INTERFACE_SUBCLASS &&
+        descriptor.interfaceProtocol === DIAG_INTERFACE_PROTOCOL);
+    if (diag !== undefined) {
+        return { state: 'descriptor-confirmed', interfaceNumber: diag.number };
+    }
+    return input.interfaces.length === 0
+        ? { state: 'not-proven', reason: 'product-id-is-not-evidence' }
+        : { state: 'not-proven', reason: 'no-diag-interface-descriptor' };
+}
+/**
+ * Unconditional. A descriptor-confirmed DIAG channel raises what a SUPERVISED BENCH
+ * operator may attempt by hand; it never raises what this package may do on its own.
+ */
+export const UFI_DIAG_PRODUCTION_ACCESS = 'prohibited';