@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/ports/ops.d.ts

@@ -0,0 +1,44 @@
+import type { DesiredRadio } from '../domain/index.js';
+import type { ConnectionId, DeviceIfname, GsmProfileInput, GsmProfilePatch } from './network-manager.js';
+/** Radio + SIM ops — owned SOLELY by the ModemManager port. */
+export type MmOp = {
+    readonly kind: 'setRadioModes';
+    readonly preference: DesiredRadio;
+} | {
+    readonly kind: 'setPrimarySimSlot';
+    readonly slotIndex: number;
+};
+/** Connection / APN / activation ops — owned SOLELY by the NetworkManager port. */
+export type NmOp = {
+    readonly kind: 'createGsmProfile';
+    readonly profile: GsmProfileInput;
+} | {
+    readonly kind: 'updateGsmProfile';
+    readonly connectionId: ConnectionId;
+    readonly patch: GsmProfilePatch;
+} | {
+    readonly kind: 'activate';
+    readonly connectionId: ConnectionId;
+    readonly deviceIfname: DeviceIfname;
+} | {
+    readonly kind: 'deactivate';
+    readonly connectionId: ConnectionId;
+    readonly deviceIfname: DeviceIfname;
+};
+/**
+ * A planned op tagged with its owning port. The two arms are disjoint on BOTH the
+ * `port` discriminant AND the op `kind` space, so the planner cannot emit — and a
+ * reviewer cannot write — a radio op under the NM port, or a connection op under
+ * the MM port.
+ */
+export type PortTaggedOp = {
+    readonly port: 'mm';
+    readonly op: MmOp;
+} | {
+    readonly port: 'nm';
+    readonly op: NmOp;
+};
+/** Tag an MM op for the ModemManager port. Only an `MmOp` is accepted. */
+export declare function mmOp(op: MmOp): PortTaggedOp;
+/** Tag an NM op for the NetworkManager port. Only an `NmOp` is accepted. */
+export declare function nmOp(op: NmOp): PortTaggedOp;

package/dist/ports/ops.js

@@ -0,0 +1,16 @@
+// Port-tagged reconcile ops — a planned mutation TAGGED with the port that owns it.
+//
+// The op kinds are DISJOINT by construction: a radio / SIM op (`MmOp`) shares no
+// `kind` with a connection / APN op (`NmOp`). Tagging is therefore type-checked —
+// `{ port: 'nm', op: { kind: 'setRadioModes', … } }` does NOT compile, because a
+// radio op is not assignable to the NM arm. That mis-tag is a COMPILE-TIME error
+// (see `ops.type-test.ts` for the `@ts-expect-error` proofs). This is the ownership
+// matrix (README) enforced by the type system, not merely by convention.
+/** Tag an MM op for the ModemManager port. Only an `MmOp` is accepted. */
+export function mmOp(op) {
+    return { port: 'mm', op };
+}
+/** Tag an NM op for the NetworkManager port. Only an `NmOp` is accepted. */
+export function nmOp(op) {
+    return { port: 'nm', op };
+}

package/{src/ports/receipts.ts → dist/ports/receipts.d.ts}

@@ -1,19 +1,5 @@
-// Reconcile receipts — the HONEST outcome of trying to apply one policy dimension.
-//
-// Every attempt to converge a dimension yields exactly one receipt with a status
-// AND a reason. Nothing is ever silently dropped: "prefer 5G" on a 4G-only modem is
-// reported as `unsupported` with a reason, never quietly downgraded to "5G off".
-
 /** The policy dimension a receipt is about. */
-export type PolicyDimension =
-	| 'enabled'
-	| 'connection'
-	| 'roaming'
-	| 'radio'
-	| 'simSlot'
-	| 'recovery'
-	| 'usage';
-
+export type PolicyDimension = 'enabled' | 'connection' | 'roaming' | 'radio' | 'band' | 'simSlot' | 'recovery' | 'usage';
 /**
  * Receipt status taxonomy:
  *   - applied     — the desired state is in effect (converged, or already was).
@@ -22,22 +8,14 @@ export type PolicyDimension =
  *   - failed      — an op was attempted and errored.
  */
 export type ReceiptStatus = 'applied' | 'pending' | 'unsupported' | 'failed';
-
 /**
  * One reconcile receipt. `reason` is ALWAYS populated — a receipt with no reason
  * would be a silent outcome, which the contract forbids.
  */
 export interface Receipt {
-	readonly dimension: PolicyDimension;
-	readonly status: ReceiptStatus;
-	readonly reason: string;
+    readonly dimension: PolicyDimension;
+    readonly status: ReceiptStatus;
+    readonly reason: string;
 }
-
 /** Build a receipt. Kept as a helper so `reason` can never be forgotten. */
-export function receipt(
-	dimension: PolicyDimension,
-	status: ReceiptStatus,
-	reason: string,
-): Receipt {
-	return { dimension, status, reason };
-}
+export declare function receipt(dimension: PolicyDimension, status: ReceiptStatus, reason: string): Receipt;

package/dist/ports/receipts.js

@@ -0,0 +1,9 @@
+// Reconcile receipts — the HONEST outcome of trying to apply one policy dimension.
+//
+// Every attempt to converge a dimension yields exactly one receipt with a status
+// AND a reason. Nothing is ever silently dropped: "prefer 5G" on a 4G-only modem is
+// reported as `unsupported` with a reason, never quietly downgraded to "5G off".
+/** Build a receipt. Kept as a helper so `reason` can never be forgotten. */
+export function receipt(dimension, status, reason) {
+    return { dimension, status, reason };
+}

package/dist/ports/reconcile.d.ts

@@ -0,0 +1,33 @@
+import type { DesiredCellularPolicy, NmActivation, RadioAccessTechnology } from '../domain/index.js';
+import type { ConnectionId, DeviceIfname } from './network-manager.js';
+import { type PortTaggedOp } from './ops.js';
+import { type Receipt } from './receipts.js';
+/** What the modem / stack can actually do — the capability set the planner honors. */
+export interface ModemCapabilities {
+    readonly supportedRats: ReadonlySet<RadioAccessTechnology>;
+    readonly simSlotCount: number;
+    readonly supportsAutoApn: boolean;
+}
+/**
+ * The currently-applied cellular configuration, as the planner sees it — the "is"
+ * state, distinct from the observational snapshot: it tracks what has actually been
+ * written (profile, radio preference, primary slot) plus the live NM activation.
+ */
+export interface AppliedCellularState {
+    readonly nmActivation: NmActivation;
+    readonly hasProfile: boolean;
+    readonly connectionId?: ConnectionId;
+    readonly deviceIfname?: DeviceIfname;
+    readonly appliedApn?: 'auto' | string;
+    readonly appliedRoaming?: boolean;
+    readonly appliedRadioPreference?: readonly RadioAccessTechnology[];
+    readonly activePrimarySlot?: number;
+    readonly activationFailureReason?: string;
+}
+/** A reconcile plan: the ops to run and one receipt per policy dimension. */
+export interface Plan {
+    readonly ops: readonly PortTaggedOp[];
+    readonly receipts: readonly Receipt[];
+}
+/** Reconcile a desired policy against the applied state into ops + receipts. */
+export declare function planReconcile(current: AppliedCellularState, desired: DesiredCellularPolicy, capabilities: ModemCapabilities): Plan;

package/dist/ports/reconcile.js

@@ -0,0 +1,200 @@
+// The desired-state planner — pure. Given the currently-applied state, a desired
+// policy, and the modem's capabilities, it produces the port-tagged ops needed to
+// converge PLUS an honest receipt per policy dimension. It performs no I/O and no
+// side effects: the same inputs always yield the same ops and receipts, which is
+// what makes re-applying a policy idempotent (see reconcile.test.ts).
+import { mmOp, nmOp } from './ops.js';
+import { receipt } from './receipts.js';
+/** Reconcile a desired policy against the applied state into ops + receipts. */
+export function planReconcile(current, desired, capabilities) {
+    const profile = planNmProfile(current, desired, capabilities);
+    const results = [
+        planRadio(current, desired, capabilities),
+        planSimSlot(current, desired, capabilities),
+        planEnabled(current, desired),
+        { receipt: planRecovery(desired) },
+        { receipt: planUsage(desired) },
+    ];
+    const ops = [];
+    const receipts = [profile.connection, profile.roaming];
+    if (profile.op !== undefined) {
+        ops.push(profile.op);
+    }
+    for (const result of results) {
+        receipts.push(result.receipt);
+        if (result.op !== undefined) {
+            ops.push(result.op);
+        }
+    }
+    return { ops, receipts };
+}
+function profileFromPolicy(desired) {
+    const auto = desired.connection.apn === 'auto';
+    const base = {
+        connectionName: 'ceralive-cellular',
+        apn: auto ? '' : desired.connection.apn,
+        homeOnly: !desired.roaming,
+        autoConfig: auto,
+    };
+    // SENSITIVE creds only when explicitly provided AND not in auto-config mode.
+    if (!auto && desired.connection.auth !== undefined) {
+        const { username, password } = desired.connection.auth;
+        return {
+            ...base,
+            ...(username !== undefined ? { username } : {}),
+            ...(password !== undefined ? { password } : {}),
+        };
+    }
+    return base;
+}
+// NM owns APN / auth / roaming / autoconnect: one profile write converges all of
+// them, so connection + roaming share a single op and each get their own receipt.
+function planNmProfile(current, desired, capabilities) {
+    const auto = desired.connection.apn === 'auto';
+    if (auto && !capabilities.supportsAutoApn) {
+        return {
+            connection: receipt('connection', 'unsupported', 'Auto-APN is not available on this NetworkManager / modem'),
+            roaming: receipt('roaming', 'unsupported', 'roaming cannot be applied without a connection profile'),
+        };
+    }
+    const needsWrite = !current.hasProfile ||
+        current.appliedApn !== desired.connection.apn ||
+        current.appliedRoaming !== desired.roaming;
+    if (!needsWrite) {
+        return {
+            connection: receipt('connection', 'applied', `connection APN '${desired.connection.apn}' already configured`),
+            roaming: receipt('roaming', 'applied', `roaming already ${desired.roaming ? 'enabled' : 'disabled'}`),
+        };
+    }
+    const op = current.hasProfile && current.connectionId !== undefined
+        ? nmOp({
+            kind: 'updateGsmProfile',
+            connectionId: current.connectionId,
+            patch: profileFromPolicy(desired),
+        })
+        : nmOp({ kind: 'createGsmProfile', profile: profileFromPolicy(desired) });
+    const verb = current.hasProfile ? 'updating' : 'creating';
+    return {
+        connection: receipt('connection', 'pending', `${verb} connection profile for APN '${desired.connection.apn}'`),
+        roaming: receipt('roaming', 'pending', `roaming ${desired.roaming ? 'enabled' : 'disabled'} via connection profile`),
+        op,
+    };
+}
+function radioMatches(applied, desired) {
+    if (applied === undefined || applied.length !== desired.length) {
+        return false;
+    }
+    return applied.every((rat, index) => rat === desired[index]);
+}
+function planRadio(current, desired, capabilities) {
+    const preference = desired.radio.preferenceOrdered;
+    const top = preference[0];
+    if (top === undefined) {
+        return {
+            receipt: receipt('radio', 'failed', 'radio preference must list at least one access technology'),
+        };
+    }
+    if (!capabilities.supportedRats.has(top)) {
+        const supported = [...capabilities.supportedRats].join(', ') || 'none';
+        return {
+            receipt: receipt('radio', 'unsupported', `preferred radio access technology '${top}' is not supported by this modem (supports ${supported})`),
+        };
+    }
+    if (radioMatches(current.appliedRadioPreference, preference)) {
+        return {
+            receipt: receipt('radio', 'applied', `radio preference already ${preference.join(' > ')}`),
+        };
+    }
+    return {
+        receipt: receipt('radio', 'pending', `setting radio preference to ${preference.join(' > ')}`),
+        op: mmOp({ kind: 'setRadioModes', preference: desired.radio }),
+    };
+}
+function planSimSlot(current, desired, capabilities) {
+    if (desired.simSlot === undefined) {
+        return { receipt: receipt('simSlot', 'applied', 'no primary SIM slot preference set') };
+    }
+    if (capabilities.simSlotCount <= 1) {
+        return {
+            receipt: receipt('simSlot', 'unsupported', `primary SIM slot selection requires a multi-slot modem (this modem has ${capabilities.simSlotCount})`),
+        };
+    }
+    if (desired.simSlot < 1 || desired.simSlot > capabilities.simSlotCount) {
+        return {
+            receipt: receipt('simSlot', 'failed', `SIM slot ${desired.simSlot} is out of range (1..${capabilities.simSlotCount})`),
+        };
+    }
+    if (current.activePrimarySlot === desired.simSlot) {
+        return {
+            receipt: receipt('simSlot', 'applied', `SIM slot ${desired.simSlot} already primary`),
+        };
+    }
+    return {
+        receipt: receipt('simSlot', 'pending', `switching primary SIM slot to ${desired.simSlot}`),
+        op: mmOp({ kind: 'setPrimarySimSlot', slotIndex: desired.simSlot }),
+    };
+}
+function planEnabled(current, desired) {
+    const nm = current.nmActivation;
+    const addressable = current.connectionId !== undefined && current.deviceIfname !== undefined;
+    if (desired.enabled) {
+        switch (nm) {
+            case 'activated':
+                return { receipt: receipt('enabled', 'applied', 'connection is active') };
+            case 'activating':
+                return { receipt: receipt('enabled', 'pending', 'connection activation in progress') };
+            case 'failed':
+                return {
+                    receipt: receipt('enabled', 'failed', `connection activation failed${current.activationFailureReason ? `: ${current.activationFailureReason}` : ''}`),
+                };
+            case 'unmanaged':
+                return {
+                    receipt: receipt('enabled', 'unsupported', 'device is not managed by NetworkManager'),
+                };
+            default:
+                if (!addressable ||
+                    current.connectionId === undefined ||
+                    current.deviceIfname === undefined) {
+                    return {
+                        receipt: receipt('enabled', 'pending', 'awaiting connection profile and data interface before activation'),
+                    };
+                }
+                return {
+                    receipt: receipt('enabled', 'pending', 'activating connection'),
+                    op: nmOp({
+                        kind: 'activate',
+                        connectionId: current.connectionId,
+                        deviceIfname: current.deviceIfname,
+                    }),
+                };
+        }
+    }
+    if ((nm === 'activated' || nm === 'activating') &&
+        current.connectionId !== undefined &&
+        current.deviceIfname !== undefined) {
+        return {
+            receipt: receipt('enabled', 'pending', 'deactivating connection'),
+            op: nmOp({
+                kind: 'deactivate',
+                connectionId: current.connectionId,
+                deviceIfname: current.deviceIfname,
+            }),
+        };
+    }
+    return { receipt: receipt('enabled', 'applied', 'connection is inactive') };
+}
+// Recovery + usage are LOCAL-CONTROLLER owned (README ownership table): they emit no
+// MM / NM op, only a receipt recording that the local policy was accepted.
+function planRecovery(desired) {
+    return receipt('recovery', 'applied', desired.recovery.enabled ? 'recovery policy recorded (enabled)' : 'recovery disabled (default)');
+}
+function planUsage(desired) {
+    const parts = [];
+    if (desired.usage.cycleDay !== undefined) {
+        parts.push(`cycle day ${desired.usage.cycleDay}`);
+    }
+    if (desired.usage.thresholdBytes !== undefined) {
+        parts.push(`threshold ${desired.usage.thresholdBytes} bytes`);
+    }
+    return receipt('usage', 'applied', parts.length > 0 ? `usage policy recorded (${parts.join(', ')})` : 'no usage policy set');
+}

package/dist/ports/resource-ownership.d.ts

@@ -0,0 +1,29 @@
+export declare const DEFAULT_MODEM_CONTROL_LOCK_PATH = "/run/ceralive/modem-control.lock";
+export type ExclusiveResource = 'file-store' | 'router-session' | 'usb-hub';
+export type ResourceOwnershipRequest = {
+    readonly resource: ExclusiveResource;
+};
+export type ResourceOwnershipHolder = {
+    readonly pid: number;
+    readonly startedAtEpochMs: number;
+};
+export type ResourceOwnershipLoss = {
+    readonly reason: 'holder-exited';
+};
+export interface ResourceOwnershipLease {
+    readonly holder: ResourceOwnershipHolder;
+    readonly lost: Promise<ResourceOwnershipLoss>;
+    release(): Promise<void>;
+}
+export type ResourceOwnershipResult = {
+    readonly status: 'acquired';
+    readonly lease: ResourceOwnershipLease;
+} | {
+    readonly status: 'refused';
+    readonly reason: 'already-owned';
+    readonly holder?: ResourceOwnershipHolder;
+};
+/** Acquire-or-refuse ownership; implementations must never queue a contender. */
+export interface ResourceOwnershipPort {
+    acquire(request: ResourceOwnershipRequest): Promise<ResourceOwnershipResult>;
+}

package/dist/ports/resource-ownership.js

@@ -0,0 +1 @@
+export const DEFAULT_MODEM_CONTROL_LOCK_PATH = '/run/ceralive/modem-control.lock';

package/dist/ports/router.d.ts

@@ -0,0 +1,19 @@
+import type { EpochMillis } from '../domain/index.js';
+import type { DeviceIfname } from './network-manager.js';
+/** Whether a router-class device is present on an interface. */
+export type RouterPresence = 'present' | 'absent';
+/**
+ * Advisory health of a router-class uplink. Every field is informational — a
+ * degraded router is reported, never removed from the routing set on health alone.
+ */
+export interface RouterHealth {
+    readonly presence: RouterPresence;
+    readonly gatewayReachable: boolean;
+    readonly egressHealthy: boolean;
+    readonly observedAt: EpochMillis;
+}
+/** The router port — presence and advisory health only. No mutation verbs. */
+export interface RouterPort {
+    probePresence(ifname: DeviceIfname): Promise<RouterPresence>;
+    checkHealth(ifname: DeviceIfname): Promise<RouterHealth>;
+}

package/dist/ports/router.js

@@ -0,0 +1,7 @@
+// The router port — for devices MM cannot control (HiLink, router-ethernet class).
+//
+// This port is DELIBERATELY tiny: presence and advisory health ONLY. Health never
+// drives activation or recovery — a degraded router stays in the routing set (it is
+// never evicted on health alone). A router device is an Ethernet uplink we OBSERVE,
+// not a modem we configure; there is no bearer / APN / radio verb here.
+export {};

package/dist/ports/sms.d.ts

@@ -0,0 +1,64 @@
+import type { Unsubscribe } from './observation.js';
+/** A message's lifecycle state, verbatim from ModemManager's own vocabulary. */
+export type SmsState = 'unknown' | 'stored' | 'receiving' | 'received' | 'sending' | 'sent';
+/** One stored message, normalized. `text` is `''` for a data-only (WAP/PDU) message. */
+export interface SmsMessage {
+    /** The trailing `/SMS/<n>` object index, stringified. */
+    readonly id: string;
+    readonly from?: string;
+    /** The service-centre timestamp, verbatim as the device reported it. */
+    readonly timestamp?: string;
+    readonly text: string;
+    readonly state: SmsState;
+}
+/**
+ * Why an inbox read produced no list. These are the four operator-actionable
+ * facts, and they are deliberately distinct from one another — a modem with no
+ * Messaging interface, a radio that has not come up, a selector nothing answers
+ * to, and drift in whatever the source printed are four different next steps.
+ */
+export type SmsReadRefusal = 'unsupported' | 'not_enabled' | 'unknown_modem' | 'read_failed';
+/**
+ * The result of an inbox read. A REFUSAL IS NEVER AN EMPTY LIST: `{ok: true,
+ * messages: []}` means this modem has an inbox and it is empty.
+ */
+export type SmsInboxResult = {
+    readonly ok: true;
+    readonly messages: readonly SmsMessage[];
+} | {
+    readonly ok: false;
+    readonly reason: SmsReadRefusal;
+};
+/**
+ * One inbox change. `resynced` carries a full authoritative list and is what a
+ * source restart produces — a consumer replaces its rows with it rather than
+ * merging, so a restart can never duplicate a row it already holds.
+ */
+export type SmsInboxEvent = {
+    readonly kind: 'added';
+    readonly message: SmsMessage;
+} | {
+    readonly kind: 'deleted';
+    readonly id: string;
+} | {
+    readonly kind: 'resynced';
+    readonly messages: readonly SmsMessage[];
+};
+export type SmsInboxListener = (event: SmsInboxEvent) => void;
+/**
+ * The read-only SMS port. `list()` resolves the current inbox once; `observe()`
+ * streams every subsequent change; `stop()` releases the source.
+ *
+ * It is deliberately NOT an extension of `ModemManagerPort`: a consumer that
+ * only reads an inbox must not acquire radio, SIM, or inhibit verbs along the
+ * way — the same narrowing argument `ModemObservationPort` makes for the
+ * shadow reader.
+ */
+export interface SmsObservationPort {
+    /** Read the modem's stored inbox, newest-first and capped. */
+    list(): Promise<SmsInboxResult>;
+    /** Subscribe to Added/Deleted/resync events. Returns an unsubscribe. */
+    observe(listener: SmsInboxListener): Unsubscribe;
+    /** Release the source. Idempotent. */
+    stop(): Promise<void>;
+}

package/dist/ports/sms.js

@@ -0,0 +1,24 @@
+// The SMS port — LIST / READ and Added/Deleted observation. NOTHING ELSE.
+//
+// READ-ONLY IS PERMANENT, NOT A PHASE LIMITATION. There is no verb here that
+// composes, stores, sends, or deletes a message, and none may ever be added.
+// Sending or deleting an SMS is billable and irreversible, and it turns a
+// diagnostic read into real modem-control capability over the subscriber's
+// account. CeraUI carries the same contract on its own side, enforced by a grep
+// gate (`tests/modem-sms-readonly-gate.test.ts`); `sms/readonly-gate.test.ts`
+// is this package's half. Neither may be weakened to land a write path — that
+// is a new spec change with its own confirmation/interlock design.
+//
+// THE OBSERVATION MODEL IS "LIST ONCE, THEN FOLLOW THE SIGNALS". ModemManager's
+// Messaging interface emits `Added` and `Deleted` for every inbox change, so a
+// consumer lists once at start and folds events from then on. Re-listing on a
+// poll tick is the anti-pattern this port exists to remove: it costs one method
+// call per message per tick and still cannot report an arrival any sooner than
+// the tick it lands on.
+//
+// CONTENT NEVER RIDES A DIAGNOSTIC. A message body routinely carries a one-time
+// code and its originator identifies the subscriber, so nothing on this port
+// puts either into a reason string, a receipt, or a log line — see
+// `../redact.ts` for the key class and `../sms/mmcli-parse.ts` for the
+// content-free parse errors.
+export {};

package/dist/ports/uhubctl.d.ts

@@ -0,0 +1,6 @@
+import type { PowerCapability, PowerCycleContext, PowerCycleResult } from '../backend/power-contract.js';
+/** Consumer-supplied USB-hub actuator. This package intentionally ships no implementation. */
+export interface UhubctlPort {
+    readonly capability: PowerCapability;
+    cycle(context: PowerCycleContext): Promise<PowerCycleResult>;
+}

package/dist/ports/uhubctl.js

@@ -0,0 +1 @@
+export {};

package/dist/providers/contracts.d.ts

@@ -0,0 +1,124 @@
+import type { DeviceGeneration, ObservationEnvelope, OperationDescriptor, OperationResult, PhysicalModemId } from '../domain/index.js';
+export declare const PROVIDER_TRANSPORTS: readonly ['usb', 'pci', 'network', 'modemmanager'];
+export type ProviderTransport = (typeof PROVIDER_TRANSPORTS)[number];
+export declare const PASSIVE_FACT_KINDS: readonly ['usb', 'pci', 'interface', 'driver', 'gateway', 'model', 'firmware'];
+export type PassiveFactKind = (typeof PASSIVE_FACT_KINDS)[number];
+export type EvidenceStrength = 'none' | 'weak' | 'moderate' | 'strong';
+export type MatcherScore = 'unsupported' | 'maybe' | 'likely' | 'supported';
+export type PassiveFact = {
+    readonly kind: PassiveFactKind;
+    readonly value: string;
+};
+export type ProviderMatchRequest = {
+    readonly physicalModemId: PhysicalModemId;
+    readonly generation: DeviceGeneration;
+    readonly transport: ProviderTransport;
+    readonly passiveFacts: readonly PassiveFact[];
+    readonly composition: string;
+    readonly firmware?: string;
+};
+export type ProviderExecutionContext = ProviderMatchRequest & {
+    readonly profile: string;
+};
+export type PassiveMatcher = {
+    readonly id: string;
+    readonly fact: PassiveFactKind;
+    readonly expected: readonly string[];
+    readonly profiles: readonly string[];
+    readonly strength: Exclude<EvidenceStrength, 'none'>;
+    readonly required: boolean;
+};
+export type FingerprintResult = {
+    readonly signal: 'match' | 'mismatch' | 'unknown';
+    readonly strength: Exclude<EvidenceStrength, 'none'>;
+    readonly profiles: readonly string[];
+    readonly detail: string;
+};
+export type UnauthenticatedProbe = {
+    readonly id: string;
+    readonly run: (context: ProviderMatchRequest) => Promise<FingerprintResult>;
+};
+export type CapabilityReader = {
+    readonly id: string;
+    readonly read: (context: ProviderExecutionContext) => Promise<Omit<FingerprintResult, 'profiles'>>;
+};
+export type AuthenticatedProfileResult = {
+    readonly status: 'matched';
+    readonly profile: string;
+    readonly detail: string;
+} | {
+    readonly status: 'refused';
+    readonly detail: string;
+} | {
+    readonly status: 'unavailable';
+    readonly detail: string;
+};
+/** One algorithm and one call per generation-scoped evaluation; cycling is unrepresentable. */
+export type AuthenticatedProfile = {
+    readonly algorithm: string;
+    readonly attemptLimit: 1;
+    readonly authenticate: (context: ProviderMatchRequest, profileCandidates: readonly string[]) => Promise<AuthenticatedProfileResult>;
+};
+export type ProviderOperationsSurface = {
+    readonly access: 'read-only' | 'read-write';
+};
+export interface ProviderReadOperations<O> {
+    readonly descriptor: OperationDescriptor<never, O>;
+    readonly read: (context: ProviderExecutionContext) => Promise<OperationResult<O>>;
+}
+export interface ProviderWriteOperations<I, O> {
+    readonly descriptor: OperationDescriptor<I, O>;
+    readonly read: (context: ProviderExecutionContext) => Promise<OperationResult<O>>;
+    readonly write: (context: ProviderExecutionContext, input: I) => Promise<OperationResult<O>>;
+}
+export type ProviderContractFixture = {
+    readonly profile: string;
+    readonly request: Readonly<Record<string, unknown>>;
+    readonly response: Readonly<Record<string, unknown>>;
+};
+export interface ProviderDefinition<TObservation = unknown, TOperations extends ProviderOperationsSurface = ProviderOperationsSurface> {
+    readonly id: string;
+    readonly profileVersion: string;
+    readonly eligibleTransports: readonly ProviderTransport[];
+    readonly passiveMatchers: readonly PassiveMatcher[];
+    readonly unauthenticatedProbes: readonly UnauthenticatedProbe[];
+    readonly authenticatedProfile?: AuthenticatedProfile;
+    readonly capabilityReaders: readonly CapabilityReader[];
+    readonly observe: (context: ProviderExecutionContext) => Promise<readonly ObservationEnvelope<TObservation>[]>;
+    readonly operations: (profile: string) => TOperations;
+    readonly contractFixtures: readonly ProviderContractFixture[];
+}
+export type MatcherEvidence = {
+    readonly provider: string;
+    readonly profile: string | null;
+    readonly stage: 'transport-eligibility' | 'passive-facts' | 'unauthenticated-fingerprint' | 'authenticated-profile' | 'capability-read';
+    readonly source: string;
+    readonly signal: 'match' | 'mismatch' | 'unknown';
+    readonly strength: EvidenceStrength;
+    readonly detail: string;
+};
+type MatchResultBase = {
+    readonly score: MatcherScore;
+    readonly confidence: number;
+    readonly evidence: readonly MatcherEvidence[];
+    readonly conflicts: readonly MatcherEvidence[];
+    readonly generation: DeviceGeneration;
+    readonly physicalModemId: PhysicalModemId;
+};
+export type ProviderMatchResult = (MatchResultBase & {
+    readonly status: 'unsupported' | 'ambiguous';
+    readonly provider: null;
+    readonly profile: null;
+    readonly operations: null;
+    readonly writable: false;
+}) | (MatchResultBase & {
+    readonly status: 'selected';
+    readonly provider: string;
+    readonly profile: string;
+    readonly operations: ProviderOperationsSurface;
+    readonly writable: boolean;
+});
+export interface ProviderMatcher {
+    match(request: ProviderMatchRequest): Promise<ProviderMatchResult>;
+}
+export {};

package/dist/providers/contracts.js

@@ -0,0 +1,10 @@
+export const PROVIDER_TRANSPORTS = ['usb', 'pci', 'network', 'modemmanager'];
+export const PASSIVE_FACT_KINDS = [
+    'usb',
+    'pci',
+    'interface',
+    'driver',
+    'gateway',
+    'model',
+    'firmware',
+];

package/dist/providers/huawei-hilink/index.d.ts

@@ -0,0 +1,2 @@
+export * from './provider.js';
+export * from './transport.js';

package/dist/providers/huawei-hilink/index.js

@@ -0,0 +1,2 @@
+export * from './provider.js';
+export * from './transport.js';