@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/providers/network-manager/types.d.ts

@@ -0,0 +1,171 @@
+import type { DeviceGeneration, EpochMillis } from '../../domain/index.js';
+import type { AppliedConfiguration, DesiredProfile, NormalizationContext } from '../../observations/index.js';
+import type { ConnectionId, DeviceIfname, GsmProfileInput, Receipt } from '../../ports/index.js';
+/**
+ * NM's own device states (`NMDeviceState`), by name.
+ *
+ * The transitional members are kept rather than collapsed into "not activated",
+ * because a device in `prepare` carrying our connection is COMING UP, and reporting
+ * that as a lost bearer would turn every ordinary activation into a false alarm.
+ */
+export declare const NM_DEVICE_STATES: readonly ['unknown', 'unmanaged', 'unavailable', 'disconnected', 'prepare', 'config', 'need-auth', 'ip-config', 'ip-check', 'secondaries', 'activated', 'deactivating', 'failed'];
+export type NmDeviceState = (typeof NM_DEVICE_STATES)[number];
+/**
+ * The bearer identity all three slots compare in.
+ *
+ * `username` and `password` are deliberately NOT members. A state slot is read,
+ * compared, and surfaced in divergence output; `gsm.password` is the one field in the
+ * profile the redaction module masks everywhere else, so putting it in a comparable
+ * value would re-open that hole through a side door. The credential lives in NM, is
+ * written through the port, and is never mirrored here.
+ */
+export interface NmBearerBinding {
+    readonly connectionId: ConnectionId;
+    readonly deviceIfname: DeviceIfname;
+    readonly apn: string;
+    readonly autoConfig: boolean;
+    readonly homeOnly: boolean;
+}
+/**
+ * A bearer, or the positive absence of one.
+ *
+ * `unbound` exists so "NM answered, and it says nothing is in force on this device"
+ * is a VALUE rather than an unavailable observation. The distinction is load-bearing:
+ * an unavailable observation compares `indeterminate` against everything, which is
+ * right for "the device is gone" and wrong for "the device is here and idle" — the
+ * second is a definite divergence from a desired bearer, and an operator needs to see
+ * it as one.
+ */
+export type NmBearerState = {
+    readonly kind: 'bound';
+    readonly binding: NmBearerBinding;
+} | {
+    readonly kind: 'unbound';
+    readonly deviceIfname: DeviceIfname;
+};
+export declare function boundBearer(binding: NmBearerBinding): NmBearerState;
+export declare function unboundBearer(deviceIfname: DeviceIfname): NmBearerState;
+export declare function nmBearerBindingEquals(left: NmBearerBinding, right: NmBearerBinding): boolean;
+/** The equality `describeStateDivergence` is driven with for NM state. */
+export declare function nmBearerStateEquals(left: NmBearerState, right: NmBearerState): boolean;
+/** The connection NM reports active on a device, with the settings it put in force. */
+export interface NmObservedActiveConnection {
+    readonly connectionId: ConnectionId;
+    readonly apn: string;
+    readonly autoConfig: boolean;
+    readonly homeOnly: boolean;
+}
+/** One device exactly as NM reports it in a readout. */
+export interface NmObservedDevice {
+    readonly ifname: DeviceIfname;
+    readonly state: NmDeviceState;
+    readonly activeConnection?: NmObservedActiveConnection;
+}
+/**
+ * ONE COMPLETE NM readout — an enumeration, never a delta.
+ *
+ * That is what makes re-enumeration detectable at all: a device missing from `devices`
+ * means the device is GONE, and a delta stream has no way to say that without a
+ * removal event nobody guarantees will arrive.
+ *
+ * `context` supplies the clock, the generation and the source epoch, exactly as the
+ * observation layer requires — this adapter has no clock of its own for observations
+ * and therefore cannot stamp a readout with a time it did not come from.
+ */
+export interface NmObservationInput {
+    readonly context: NormalizationContext;
+    readonly devices: readonly NmObservedDevice[];
+}
+/** What an operator asked for: a saved profile, targeted at an exact device. */
+export interface NmDesiredRequest {
+    readonly profile: GsmProfileInput;
+    readonly deviceIfname: DeviceIfname;
+    /** Opaque origin label (an RPC caller, a policy engine). Never a credential. */
+    readonly requestedBy: string;
+    /** Update this existing profile instead of creating a new one. */
+    readonly connectionId?: ConnectionId;
+}
+export declare const NM_ADAPTER_REFUSAL_REASONS: readonly ['no-desired-profile', 'profile-absent', 'activation-failed', 'deactivation-failed', 'write-failed'];
+export type NmAdapterRefusalReason = (typeof NM_ADAPTER_REFUSAL_REASONS)[number];
+export type NmSaveResult = {
+    readonly ok: true;
+    readonly connectionId: ConnectionId;
+    readonly desired: DesiredProfile<NmBearerState>;
+} | {
+    readonly ok: false;
+    readonly reason: NmAdapterRefusalReason;
+    readonly receipt: Receipt;
+};
+/** Applying a desired profile: the write either took, or it did not and says why. */
+export type NmApplyResult = {
+    readonly ok: true;
+    readonly applied: AppliedConfiguration<NmBearerState>;
+    readonly receipt: Receipt;
+} | {
+    readonly ok: false;
+    readonly reason: NmAdapterRefusalReason;
+    readonly receipt: Receipt;
+};
+export declare const NM_APPLIED_LOSS_REASONS: readonly [
+/** The readout has no such device at all — a re-enumeration, or an unplug. */
+'interface-absent', 
+/** The device is present and carries no active connection. */
+'interface-detached', 
+/** A DIFFERENT connection is active on our device. */
+'connection-replaced', 
+/** NM reports the device itself failed. */
+'activation-failed'];
+export type NmAppliedLossReason = (typeof NM_APPLIED_LOSS_REASONS)[number];
+/**
+ * The applied bearer stopped being in force.
+ *
+ * `previous` is retained rather than discarded: a caller deciding whether to re-apply
+ * or to roll back needs to know what WAS in force, and the applied slot has just been
+ * cleared precisely because it no longer describes reality.
+ */
+export interface NmAppliedLoss {
+    readonly connectionId: ConnectionId;
+    readonly deviceIfname: DeviceIfname;
+    readonly reason: NmAppliedLossReason;
+    readonly lostAt: EpochMillis;
+    readonly generation: DeviceGeneration;
+    readonly previous: AppliedConfiguration<NmBearerState>;
+}
+export type NmAppliedOutcome = 
+/** A desired profile is tracked, and nothing has been put into force for it yet. */
+{
+    readonly status: 'unapplied';
+} | {
+    readonly status: 'retained';
+    readonly applied: AppliedConfiguration<NmBearerState>;
+} | {
+    readonly status: 'pending';
+    readonly applied: AppliedConfiguration<NmBearerState>;
+    readonly deviceState: NmDeviceState;
+} | {
+    readonly status: 'lost';
+    readonly loss: NmAppliedLoss;
+};
+export interface NmConnectionOutcome {
+    readonly connectionId: ConnectionId;
+    readonly outcome: NmAppliedOutcome;
+}
+/**
+ * The result of folding one readout.
+ *
+ * A readout from a superseded generation is REFUSED rather than applied late: the
+ * generation fence exists so a reply about a previous enumeration cannot clear applied
+ * state that belongs to the current one.
+ */
+export type NmObservationResult = {
+    readonly kind: 'refused';
+    readonly reason: 'superseded-generation';
+    readonly currentGeneration: DeviceGeneration;
+} | {
+    readonly kind: 'accepted';
+    readonly generation: DeviceGeneration;
+    readonly observedAt: EpochMillis;
+    readonly outcomes: readonly NmConnectionOutcome[];
+    /** Just the losses, so the case that matters is not behind a filter. */
+    readonly losses: readonly NmAppliedLoss[];
+};

package/dist/providers/network-manager/types.js

@@ -0,0 +1,77 @@
+// The saved-vs-applied vocabulary, in NetworkManager's own terms.
+//
+// NM is the sole writer of bearers, APN, auth, roaming, autoconnect and activation
+// (`ports/README.md` ownership matrix), and it is also the stack that draws the
+// distinction this whole module is built on: a connection PROFILE is what was saved,
+// an ACTIVE connection is what was actually put into force on a device, and the device
+// itself reports what it is currently doing. `observations/state-separation.ts` models
+// those three slots generically; this file gives them an NM-shaped payload.
+//
+// Radio, band, SIM and power operations are deliberately absent. Those belong to the
+// ModemManager provider, and a second surface expressing them here would make two
+// writers for one resource — the exact thing the ownership matrix exists to prevent.
+// Nothing here carries a `PhysicalModemId` either: every slot is keyed by NM's own
+// connection UUID, so this adapter can never become a second authority on which
+// physical modem is which.
+/**
+ * NM's own device states (`NMDeviceState`), by name.
+ *
+ * The transitional members are kept rather than collapsed into "not activated",
+ * because a device in `prepare` carrying our connection is COMING UP, and reporting
+ * that as a lost bearer would turn every ordinary activation into a false alarm.
+ */
+export const NM_DEVICE_STATES = [
+    'unknown',
+    'unmanaged',
+    'unavailable',
+    'disconnected',
+    'prepare',
+    'config',
+    'need-auth',
+    'ip-config',
+    'ip-check',
+    'secondaries',
+    'activated',
+    'deactivating',
+    'failed',
+];
+export function boundBearer(binding) {
+    return { kind: 'bound', binding };
+}
+export function unboundBearer(deviceIfname) {
+    return { kind: 'unbound', deviceIfname };
+}
+export function nmBearerBindingEquals(left, right) {
+    return (left.connectionId === right.connectionId &&
+        left.deviceIfname === right.deviceIfname &&
+        left.apn === right.apn &&
+        left.autoConfig === right.autoConfig &&
+        left.homeOnly === right.homeOnly);
+}
+/** The equality `describeStateDivergence` is driven with for NM state. */
+export function nmBearerStateEquals(left, right) {
+    if (left.kind === 'bound' && right.kind === 'bound') {
+        return nmBearerBindingEquals(left.binding, right.binding);
+    }
+    if (left.kind === 'unbound' && right.kind === 'unbound') {
+        return left.deviceIfname === right.deviceIfname;
+    }
+    return false;
+}
+export const NM_ADAPTER_REFUSAL_REASONS = [
+    'no-desired-profile',
+    'profile-absent',
+    'activation-failed',
+    'deactivation-failed',
+    'write-failed',
+];
+export const NM_APPLIED_LOSS_REASONS = [
+    /** The readout has no such device at all — a re-enumeration, or an unplug. */
+    'interface-absent',
+    /** The device is present and carries no active connection. */
+    'interface-detached',
+    /** A DIFFERENT connection is active on our device. */
+    'connection-replaced',
+    /** NM reports the device itself failed. */
+    'activation-failed',
+];

package/dist/providers/registry.d.ts

@@ -0,0 +1,13 @@
+import { DomainError } from '../domain/index.js';
+import type { ProviderDefinition, ProviderOperationsSurface } from './contracts.js';
+export declare class ProviderRegistryError extends DomainError {
+    readonly reason: 'duplicate-provider' | 'empty-profile-version';
+    readonly name = "ProviderRegistryError";
+    constructor(reason: 'duplicate-provider' | 'empty-profile-version');
+}
+export interface ProviderRegistry {
+    readonly revision: number;
+    register<TObservation, TOperations extends ProviderOperationsSurface>(definition: ProviderDefinition<TObservation, TOperations>): void;
+    list(): readonly ProviderDefinition[];
+}
+export declare function createProviderRegistry(): ProviderRegistry;

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: "match" | "unknown";
+        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>;