@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/operations/operation-engine.js

@@ -0,0 +1,194 @@
+import { canAutoRetry, classifyOperationCompletion, } from '../domain/index.js';
+import { acquireMutationAdmission } from '../ports/index.js';
+export * from './contracts.js';
+const MAX_IDEMPOTENT_READ_ATTEMPTS = 2;
+export class OperationEngine {
+    #root;
+    #currentGeneration;
+    #preconditions;
+    #reconciliationRequired = new Set();
+    constructor(options) {
+        this.#root = options.root;
+        this.#currentGeneration = options.currentGeneration;
+        this.#preconditions = options.preconditions;
+    }
+    invoke(execution) {
+        if (execution.descriptor.mutationImpact === 'read') {
+            return this.#invokeNow(execution);
+        }
+        return this.#root
+            .actorFor(execution.physicalModemId)
+            .run(execution.physicalModemId, () => this.#invokeNow(execution));
+    }
+    reconcile(execution) {
+        return this.#root
+            .actorFor(execution.physicalModemId)
+            .run(execution.physicalModemId, async () => {
+            const current = this.#currentGeneration(execution.physicalModemId);
+            if (!this.#reconciliationRequired.has(execution.physicalModemId)) {
+                return { status: 'not-required', generation: current };
+            }
+            if (current !== execution.generation) {
+                return { status: 'failed', reason: 'stale-generation', generation: current };
+            }
+            const result = await execution.run();
+            const completedGeneration = this.#currentGeneration(execution.physicalModemId);
+            if (completedGeneration !== execution.generation) {
+                return {
+                    status: 'failed',
+                    reason: 'stale-generation',
+                    generation: completedGeneration,
+                };
+            }
+            if (result.status === 'failed') {
+                return { ...result, generation: completedGeneration };
+            }
+            this.#reconciliationRequired.delete(execution.physicalModemId);
+            return { status: 'reconciled', generation: completedGeneration };
+        });
+    }
+    async #invokeNow(execution) {
+        const generation = this.#currentGeneration(execution.physicalModemId);
+        const kind = execution.descriptor.mutationImpact === 'read' ? 'read' : 'write';
+        if (kind === 'write' && this.#reconciliationRequired.has(execution.physicalModemId)) {
+            return refused('reconciliation-required', generation);
+        }
+        const descriptorRefusal = descriptorRefusalReason(execution);
+        if (descriptorRefusal !== undefined)
+            return refused(descriptorRefusal, generation);
+        const precondition = await this.#preconditions.check({
+            operationId: execution.operationId,
+            physicalModemId: execution.physicalModemId,
+            generation,
+            descriptorId: execution.descriptor.id,
+            preconditions: execution.descriptor.livePreconditions,
+        });
+        if (precondition.status === 'refused')
+            return refused(precondition.reason, generation);
+        const admission = await acquireMutationAdmission({
+            operationId: execution.operationId,
+            physicalModemId: execution.physicalModemId,
+            impact: execution.descriptor.mutationImpact,
+            requirement: execution.descriptor.admission,
+        }, kind === 'write' ? this.#root.admission : undefined);
+        if (admission.status === 'refused')
+            return refused(admission.reason, generation);
+        try {
+            await execution.journal?.record({
+                phase: 'started',
+                operationId: execution.operationId,
+                physicalModemId: execution.physicalModemId,
+                generation,
+                descriptor: execution.descriptor,
+                input: execution.input,
+            });
+            const result = await this.#executeWithRetry(execution, generation, kind);
+            const withHooks = await this.#runCompletionHooks(execution, result, generation);
+            if (withHooks.status === 'unknown-outcome') {
+                this.#reconciliationRequired.add(execution.physicalModemId);
+            }
+            await execution.journal?.record({
+                phase: 'completed',
+                operationId: execution.operationId,
+                physicalModemId: execution.physicalModemId,
+                generation,
+                descriptor: execution.descriptor,
+                result: withHooks,
+            });
+            return withHooks;
+        }
+        finally {
+            await releaseAdmission(admission);
+        }
+    }
+    async #executeWithRetry(execution, generation, kind) {
+        for (let attempt = 1; attempt <= MAX_IDEMPOTENT_READ_ATTEMPTS; attempt += 1) {
+            const completion = await execution.execute({
+                operationId: execution.operationId,
+                generation,
+                attempt,
+            });
+            const result = classifyOperationCompletion({
+                operation: kind,
+                completionGeneration: generation,
+                currentGeneration: this.#currentGeneration(execution.physicalModemId),
+                completion,
+            });
+            if (!canAutoRetry(execution.descriptor, result) || attempt === MAX_IDEMPOTENT_READ_ATTEMPTS) {
+                return result;
+            }
+        }
+        return refused('retry-budget-exhausted', generation);
+    }
+    async #runCompletionHooks(execution, result, generation) {
+        const context = {
+            operationId: execution.operationId,
+            generation,
+            attempt: 1,
+        };
+        if (result.status === 'applied' && execution.descriptor.readback.required) {
+            const completion = await execution.readback?.(context);
+            if (completion === undefined)
+                return refused('readback-hook-missing', generation);
+            const readback = classifyOperationCompletion({
+                operation: 'read',
+                completionGeneration: generation,
+                currentGeneration: this.#currentGeneration(execution.physicalModemId),
+                completion,
+            });
+            if (readback.status === 'applied' &&
+                execution.descriptor.readback.matches(execution.input, readback.value)) {
+                return result;
+            }
+            if (readback.status === 'unknown-outcome')
+                return readback;
+            await execution.rollback?.(context);
+            return refused(readback.status === 'applied' ? 'readback-mismatch' : `readback-${readback.reason}`, generation, 'failed');
+        }
+        if (result.status === 'failed' && execution.descriptor.rollback.required) {
+            await execution.rollback?.(context);
+        }
+        return result;
+    }
+}
+export function createOperationEngine(options) {
+    return new OperationEngine(options);
+}
+function descriptorRefusalReason(execution) {
+    const { descriptor } = execution;
+    const support = descriptor.mutationImpact === 'read' ? descriptor.support.read : descriptor.support.write;
+    if (!support.supported)
+        return support.reason;
+    if (descriptor.availability.state !== 'available')
+        return descriptor.availability.reason;
+    if (!inputAllowed(descriptor, execution.input))
+        return 'constraint-refused';
+    if (descriptor.readback.required && execution.readback === undefined)
+        return 'readback-hook-missing';
+    if (descriptor.rollback.required && execution.rollback === undefined)
+        return 'rollback-hook-missing';
+    if (descriptor.journal.required && execution.journal === undefined)
+        return 'journal-hook-missing';
+    return undefined;
+}
+function inputAllowed(descriptor, input) {
+    switch (descriptor.constraints.kind) {
+        case 'unconstrained':
+            return true;
+        case 'allowed-values':
+            return descriptor.constraints.values.some((value) => Object.is(value, input));
+        case 'numeric-range':
+            return (typeof input === 'number' &&
+                input >= descriptor.constraints.min &&
+                input <= descriptor.constraints.max &&
+                (descriptor.constraints.step === undefined ||
+                    (input - descriptor.constraints.min) % descriptor.constraints.step === 0));
+    }
+}
+function refused(reason, generation, status = 'refused') {
+    return { status, reason, generation, requiresReconciliation: false };
+}
+async function releaseAdmission(admission) {
+    if (admission.status === 'admitted')
+        await admission.lease.release();
+}

package/dist/ports/index.d.ts

@@ -0,0 +1,12 @@
+export * from './location.js';
+export * from './modem-manager.js';
+export * from './mutation-admission.js';
+export * from './network-manager.js';
+export * from './observation.js';
+export * from './ops.js';
+export * from './receipts.js';
+export * from './reconcile.js';
+export * from './resource-ownership.js';
+export * from './router.js';
+export * from './sms.js';
+export * from './uhubctl.js';

package/{src/ports/index.ts → dist/ports/index.js}

@@ -6,11 +6,15 @@
 // autoconnect / activation; MM owns radio / SIM ops; the local controller owns
 // recovery + usage policy. The ModemManagerPort has NO bearer / connect verb —
 // enforced at build time by forbidden-surface.test.ts.
-
-export * from './modem-manager';
-export * from './network-manager';
-export * from './observation';
-export * from './ops';
-export * from './receipts';
-export * from './reconcile';
-export * from './router';
+export * from './location.js';
+export * from './modem-manager.js';
+export * from './mutation-admission.js';
+export * from './network-manager.js';
+export * from './observation.js';
+export * from './ops.js';
+export * from './receipts.js';
+export * from './reconcile.js';
+export * from './resource-ownership.js';
+export * from './router.js';
+export * from './sms.js';
+export * from './uhubctl.js';

package/dist/ports/location.d.ts

@@ -0,0 +1,87 @@
+import type { EpochMillis } from '../domain/index.js';
+import type { ModemRef } from './modem-manager.js';
+/**
+ * The GNSS sources `Modem.Location.Capabilities` can advertise, as decoded source
+ * names. `3gpp-lac-ci` is deliberately absent: coarse cell location is the cell-info
+ * module's surface, and MM advertises it on devices with no GNSS receiver at all.
+ */
+export declare const GNSS_SOURCES: readonly ['gps-raw', 'gps-nmea', 'gps-unmanaged', 'agps-msa', 'agps-msb'];
+export type GnssSource = (typeof GNSS_SOURCES)[number];
+/** What `Modem.Location` advertises and what is switched on right now. */
+export interface LocationStatus {
+    /** Every source name in `Capabilities`, GNSS or not (`3gpp-lac-ci` included). */
+    readonly capabilities: ReadonlySet<string>;
+    /** Every source name in `Enabled`. */
+    readonly enabledSources: ReadonlySet<string>;
+    /** True when at least one GNSS source is advertised. */
+    readonly gnssCapable: boolean;
+    /** True when at least one GNSS source is switched on. */
+    readonly gnssEnabled: boolean;
+}
+export type LocationStatusResult = {
+    readonly ok: true;
+    readonly status: LocationStatus;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * One GNSS fix. SENSITIVE: never persist it, never upload it, never put it in a log
+ * line. `observedAt` is when this process READ the fix, which is what staleness is
+ * measured against — a modem's own `utc-time` cannot be trusted to advance.
+ */
+export interface GnssFix {
+    readonly latitude: number;
+    readonly longitude: number;
+    readonly altitude?: number;
+    readonly utcTime?: string;
+    readonly observedAt: EpochMillis;
+}
+/**
+ * The outcome of ONE read attempt. `no-fix` is a first-class success: the modem
+ * answered and has not acquired a position. It is never conflated with an error and
+ * never answered with a previous fix — a stale coordinate rendered as current is the
+ * one failure mode this module exists to prevent.
+ */
+export type FixRead = {
+    readonly outcome: 'fix';
+    readonly fix: GnssFix;
+} | {
+    readonly outcome: 'no-fix';
+    readonly reason: string;
+} | {
+    readonly outcome: 'disabled';
+    readonly reason: string;
+} | {
+    readonly outcome: 'unsupported';
+    readonly reason: string;
+} | {
+    readonly outcome: 'error';
+    readonly reason: string;
+};
+/**
+ * The outcome of switching GNSS on or off. Modelled like `SimUnlockResult` rather
+ * than as a reconcile `Receipt`: GNSS is an operator-invoked, gate-defaulted-off
+ * action with no desired-state dimension, so it is not something the planner
+ * converges.
+ */
+export interface LocationToggleResult {
+    readonly outcome: 'applied' | 'unsupported' | 'failed';
+    readonly reason: string;
+    /** The GNSS sources enabled after the call — empty after a successful disable. */
+    readonly enabledSources: ReadonlySet<string>;
+}
+/**
+ * Read GNSS status, switch GNSS on/off, and read the current fix.
+ *
+ * Deliberately NOT part of `ModemManagerPort`: a consumer that only reconciles
+ * radio and SIM state has no business holding a handle that can read a position.
+ */
+export interface ModemLocationPort {
+    getLocationStatus(modem: ModemRef): Promise<LocationStatusResult>;
+    enableGnss(modem: ModemRef, sources: readonly GnssSource[]): Promise<LocationToggleResult>;
+    disableGnss(modem: ModemRef): Promise<LocationToggleResult>;
+    readFix(modem: ModemRef): Promise<FixRead>;
+}
+export declare function isGnssSource(value: string): value is GnssSource;
+export declare function hasGnssSource(sources: Iterable<string>): boolean;

package/dist/ports/location.js

@@ -0,0 +1,36 @@
+// The GNSS location port — ModemManager's `Modem.Location` interface, scoped by a
+// privacy fence that is a PRODUCT rule, not a phase limitation.
+//
+// THE FENCE: this port reads the CURRENT fix and nothing else. There is no history
+// verb, no track verb, no export verb, and no upload verb, and none may ever be
+// added — a fix is held in memory for a live display and is gone the moment GNSS is
+// disabled or the fix goes stale. `location-fence.test.ts` fails the build if a
+// member whose name implies history, tracking, persistence, or upload appears here.
+//
+// A fix also carries coordinates, which say where the operator physically is. That
+// class is redacted by `../redact` (`latitude` / `longitude` / `altitude` / `nmea`),
+// so a fix that reaches a log line or a receipt comes out as the redaction marker
+// rather than a position.
+/**
+ * The GNSS sources `Modem.Location.Capabilities` can advertise, as decoded source
+ * names. `3gpp-lac-ci` is deliberately absent: coarse cell location is the cell-info
+ * module's surface, and MM advertises it on devices with no GNSS receiver at all.
+ */
+export const GNSS_SOURCES = [
+    'gps-raw',
+    'gps-nmea',
+    'gps-unmanaged',
+    'agps-msa',
+    'agps-msb',
+];
+export function isGnssSource(value) {
+    return GNSS_SOURCES.includes(value);
+}
+export function hasGnssSource(sources) {
+    for (const source of sources) {
+        if (isGnssSource(source)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/ports/modem-manager.d.ts

@@ -0,0 +1,89 @@
+import type { DesiredRadio, EpochMillis, RuntimePath } from '../domain/index.js';
+import type { ModemObservationPort } from './observation.js';
+import type { Receipt } from './receipts.js';
+/** A live handle to one modem — its ModemManager D-Bus object path (per-boot). */
+export type ModemRef = RuntimePath;
+/** Outcome of a SIM PIN unlock attempt. */
+export interface SimUnlockResult {
+    readonly outcome: 'unlocked' | 'incorrect-pin' | 'sim-puk-required' | 'unsupported' | 'error';
+    readonly remainingAttempts?: number;
+    readonly reason: string;
+}
+/** Outcome of a SIM PUK unblock attempt. */
+export interface SimPukUnlockResult {
+    readonly outcome: 'unlocked' | 'incorrect-puk' | 'permanently-blocked' | 'unsupported' | 'error';
+    readonly remainingAttempts?: number;
+    readonly reason: string;
+}
+/** One operator returned by a network scan. */
+export interface ScannedNetwork {
+    /** MCC+MNC operator code. */
+    readonly operatorCode: string;
+    readonly operatorName?: string;
+    readonly availability: 'available' | 'current' | 'forbidden' | 'unknown';
+}
+/** Result of a network scan — discriminated, retaining the reason on failure. */
+export type NetworkScanResult = {
+    readonly ok: true;
+    readonly networks: readonly ScannedNetwork[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * What a modem says about its bands, right now.
+ *
+ * `supported` and `current` are BOTH required, and both may legitimately be
+ * empty: a modem that advertises no band control answers an empty `supported`,
+ * which is a real reading and the thing that keeps a control from being offered.
+ * A read that could not happen at all is the `ok: false` arm instead — the same
+ * "unknown is an answer about the READ" split the capability probes follow.
+ */
+export interface ModemBands {
+    readonly supported: readonly string[];
+    readonly current: readonly string[];
+}
+export type BandReadResult = {
+    readonly ok: true;
+    readonly bands: ModemBands;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** A held inhibition over a modem, released via `uninhibit`. */
+export interface InhibitLease {
+    /** The equipment UID the inhibition is keyed to. */
+    readonly uid: string;
+    readonly acquiredAt: EpochMillis;
+}
+/**
+ * The ModemManager port — EXTENDS the read-only observation port with the modem
+ * mutations MM legitimately owns: radio modes, primary SIM slot, PIN / PUK unlock,
+ * network scan, and inhibit / uninhibit. It owns NO bearer / connection lifecycle;
+ * bearers and activation belong to `NetworkManagerPort`.
+ */
+export interface ModemManagerInhibitPort {
+    /** Inhibit MM from managing a device (for a maintenance lease), keyed by UID. */
+    inhibit(uid: string): Promise<InhibitLease>;
+    /** Release a previously-taken inhibition. */
+    uninhibit(lease: InhibitLease): Promise<void>;
+}
+export interface ModemManagerPort extends ModemObservationPort, ModemManagerInhibitPort {
+    /** Set the modem's radio access-technology preference. */
+    setRadioModes(modem: ModemRef, preference: DesiredRadio): Promise<Receipt>;
+    /** Read the modem's supported and currently-selected bands. */
+    readBands(modem: ModemRef): Promise<BandReadResult>;
+    /**
+     * Lock the modem to a band selection. Passing exactly `['any']` releases the
+     * lock — ModemManager has no separate reset verb, so this IS the reset.
+     */
+    setCurrentBands(modem: ModemRef, bands: readonly string[]): Promise<Receipt>;
+    /** Select the primary SIM slot (multi-slot modems only). */
+    setPrimarySimSlot(modem: ModemRef, slotIndex: number): Promise<Receipt>;
+    /** Submit a SIM PIN (exactly-once; read-before-submit is the adapter's job). */
+    sendPin(modem: ModemRef, pin: string): Promise<SimUnlockResult>;
+    /** Submit a SIM PUK plus the new PIN (exactly-once). */
+    sendPuk(modem: ModemRef, puk: string, newPin: string): Promise<SimPukUnlockResult>;
+    /** Scan for visible networks (long-running). */
+    scanNetworks(modem: ModemRef): Promise<NetworkScanResult>;
+}

package/dist/ports/modem-manager.js

@@ -0,0 +1,9 @@
+// The ModemManager port — radio, SIM, scan, inhibit, and observation.
+//
+// CRITICAL INVARIANT (the single most safety-critical constraint in the package):
+// this port has NO bearer / connection verb. There is no connect, no createBearer,
+// no bearerConnect — MM's Simple.Connect / CreateBearer / Bearer.Connect are NEVER
+// callable through here. NetworkManager is the sole owner of bearers and activation
+// (see README ownership table). `forbidden-surface.test.ts` fails the build if any
+// such method is ever added to this file.
+export {};

package/dist/ports/mutation-admission.d.ts

@@ -0,0 +1,27 @@
+import type { MutationImpact, OperationRequirement, PhysicalModemId } from '../domain/index.js';
+export type MutationAdmissionRequest = {
+    readonly operationId: string;
+    readonly physicalModemId: PhysicalModemId;
+    readonly impact: MutationImpact;
+    readonly requirement: OperationRequirement;
+};
+export interface MutationAdmissionLease {
+    release(): Promise<void>;
+}
+export type MutationAdmissionRefusalReason = 'admission-port-missing' | 'admission-refused';
+export type MutationAdmissionDecision = {
+    readonly status: 'admitted';
+    readonly lease: MutationAdmissionLease;
+} | {
+    readonly status: 'refused';
+    readonly reason: MutationAdmissionRefusalReason;
+    readonly detail?: string;
+};
+export type MutationAdmissionResult = {
+    readonly status: 'not-required';
+} | MutationAdmissionDecision;
+/** Consumer-owned admission authority. The package neither derives nor interprets its policy. */
+export interface MutationAdmissionPort {
+    acquire(request: MutationAdmissionRequest): Promise<MutationAdmissionDecision>;
+}
+export declare function acquireMutationAdmission(request: MutationAdmissionRequest, port: MutationAdmissionPort | undefined): Promise<MutationAdmissionResult>;

package/dist/ports/mutation-admission.js

@@ -0,0 +1,9 @@
+export function acquireMutationAdmission(request, port) {
+    if (!request.requirement.required) {
+        return Promise.resolve({ status: 'not-required' });
+    }
+    if (port === undefined) {
+        return Promise.resolve({ status: 'refused', reason: 'admission-port-missing' });
+    }
+    return port.acquire(request);
+}

package/dist/ports/network-manager.d.ts

@@ -0,0 +1,68 @@
+import type { Brand, EpochMillis } from '../domain/index.js';
+import type { Receipt } from './receipts.js';
+/** A NetworkManager connection-profile UUID. */
+export type ConnectionId = Brand<string, 'ConnectionId'>;
+/** A kernel network-device interface name (e.g. `wwan0`). */
+export type DeviceIfname = Brand<string, 'DeviceIfname'>;
+/** Construct a `ConnectionId` from a non-empty NM connection UUID. */
+export declare function connectionId(value: string): ConnectionId;
+/** Construct a `DeviceIfname` from a non-empty interface name. */
+export declare function deviceIfname(value: string): DeviceIfname;
+/**
+ * A GSM connection profile — NM's `gsm.*` setting group. `password` is SENSITIVE
+ * and MUST be redacted in every log / output (see `../redact`). The full nine-field
+ * nmcli write parity lands with the concrete adapter (A4.1); this is the port
+ * contract that adapter fulfils.
+ */
+export interface GsmProfileInput {
+    readonly connectionName: string;
+    /** Concrete APN, or the empty string when `autoConfig` drives it (A4.1). */
+    readonly apn: string;
+    readonly username?: string;
+    /** SENSITIVE — redact everywhere. */
+    readonly password?: string;
+    /** `true` ⇒ `gsm.home-only` (roaming disabled). */
+    readonly homeOnly: boolean;
+    /** `true` ⇒ `gsm.auto-config yes` (Auto-APN); mutually exclusive with creds. */
+    readonly autoConfig: boolean;
+    /** Manual operator selection (`gsm.network-id`); empty unless roaming-pinned. */
+    readonly networkId?: string;
+}
+/** A persisted GSM profile as read back from NM, keyed by its connection id. */
+export interface GsmProfile extends GsmProfileInput {
+    readonly connectionId: ConnectionId;
+}
+/** A partial update to an existing GSM profile. */
+export type GsmProfilePatch = Partial<GsmProfileInput>;
+/**
+ * A quiesce lease — a held guarantee that the connection on THIS exact device stays
+ * deactivated while a disruptive MM operation runs, then is reactivated on release.
+ * Bound to BOTH `connectionId` and `deviceIfname` so it can never quiesce the wrong
+ * device (the two-device isolation invariant, A4.1).
+ */
+export interface QuiesceLease {
+    readonly connectionId: ConnectionId;
+    readonly deviceIfname: DeviceIfname;
+    readonly acquiredAt: EpochMillis;
+}
+/**
+ * The NetworkManager port. Activation and deactivation take BOTH the connection id
+ * AND the device interface name — never an id alone. This encodes, at the type
+ * level, that we address a connection on an EXACT device (`nmcli connection up
+ * <uuid> ifname <dev>` / verify-then-`device disconnect <ifname>`); the id-only
+ * `nmcli connection down` is structurally impossible to express here (A4.1).
+ */
+export interface NetworkManagerPort {
+    createGsmProfile(profile: GsmProfileInput): Promise<GsmProfile>;
+    readGsmProfile(id: ConnectionId): Promise<GsmProfile | undefined>;
+    updateGsmProfile(id: ConnectionId, patch: GsmProfilePatch): Promise<GsmProfile>;
+    deleteGsmProfile(id: ConnectionId): Promise<void>;
+    /** Activate `id` on the EXACT device `ifname`. */
+    activate(id: ConnectionId, ifname: DeviceIfname): Promise<Receipt>;
+    /** Deactivate `id` on the EXACT device `ifname`. */
+    deactivate(id: ConnectionId, ifname: DeviceIfname): Promise<Receipt>;
+    /** Take a quiesce lease over `id` on the EXACT device `ifname`. */
+    acquireQuiesceLease(id: ConnectionId, ifname: DeviceIfname): Promise<QuiesceLease>;
+    /** Release a quiesce lease, reactivating the connection it held down. */
+    releaseQuiesceLease(lease: QuiesceLease): Promise<void>;
+}

package/dist/ports/network-manager.js

@@ -0,0 +1,13 @@
+// The NetworkManager port — NM is the SOLE owner of bearers, APN, auth, roaming,
+// autoconnect, and activation (see README ownership table). This port is the ONLY
+// way the controller touches any of those resources; the ModemManager port has no
+// bearer / connection verbs at all.
+import { nonEmptyString } from '../domain/index.js';
+/** Construct a `ConnectionId` from a non-empty NM connection UUID. */
+export function connectionId(value) {
+    return nonEmptyString(value, 'connectionId');
+}
+/** Construct a `DeviceIfname` from a non-empty interface name. */
+export function deviceIfname(value) {
+    return nonEmptyString(value, 'deviceIfname');
+}

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

@@ -1,18 +1,8 @@
-// The observation contract — the read side shared by every ModemManager backend.
-//
-// `ModemObservationPort` is the NARROW port: it observes modems and reports them as
-// a stream of discriminated list results. It carries NO mutation methods at all.
-// The full `ModemManagerPort` (mutations) EXTENDS this, so a shadow / read-only
-// consumer can depend on observation alone and never gain a mutating verb.
-
-import type { CellularSnapshot } from '../domain';
-
+import type { CellularSnapshot } from '../domain/index.js';
 /** Cancels a subscription created by `observe`. Calling it twice is a no-op. */
 export type Unsubscribe = () => void;
-
 /** Why an observation could not produce an authoritative list this cycle. */
 export type ObservationFailureReason = 'not-started' | 'source-unavailable' | 'bus-error';
-
 /**
  * The result of listing modems — DISCRIMINATED on `ok`, and it NEVER throws away
  * rows. Even the failure arm carries `rows`: the last-known modems are RETAINED so
@@ -20,18 +10,17 @@ export type ObservationFailureReason = 'not-started' | 'source-unavailable' | 'b
  * expressed by an `ok: true` snapshot that OMITS a modem (A3.1 epoch authority) —
  * the false-removal class is dead by construction.
  */
-export type ObservationList<T = CellularSnapshot> =
-	| { readonly ok: true; readonly rows: readonly T[] }
-	| {
-			readonly ok: false;
-			readonly reason: ObservationFailureReason;
-			/** Retained rows from the last authoritative snapshot — never dropped. */
-			readonly rows: readonly T[];
-	  };
-
+export type ObservationList<T = CellularSnapshot> = {
+    readonly ok: true;
+    readonly rows: readonly T[];
+} | {
+    readonly ok: false;
+    readonly reason: ObservationFailureReason;
+    /** Retained rows from the last authoritative snapshot — never dropped. */
+    readonly rows: readonly T[];
+};
 /** A subscriber to the ongoing observation stream. */
 export type ObservationListener<T = CellularSnapshot> = (list: ObservationList<T>) => void;
-
 /**
  * The read-only observation port. `start()` connects, subscribes, and resolves the
  * first AUTHORITATIVE list; `observe()` streams every subsequent list (each snapshot
@@ -39,10 +28,10 @@ export type ObservationListener<T = CellularSnapshot> = (list: ObservationList<T
  * here can change modem state — that narrowness is the whole point of the port.
  */
 export interface ModemObservationPort {
-	/** Connect, subscribe, and resolve the first authoritative observation list. */
-	start(): Promise<ObservationList>;
-	/** Subscribe to the ongoing stream of observation lists. Returns an unsubscribe. */
-	observe(listener: ObservationListener): Unsubscribe;
-	/** Tear down the subscription and release the source. Idempotent. */
-	stop(): Promise<void>;
+    /** Connect, subscribe, and resolve the first authoritative observation list. */
+    start(): Promise<ObservationList>;
+    /** Subscribe to the ongoing stream of observation lists. Returns an unsubscribe. */
+    observe(listener: ObservationListener): Unsubscribe;
+    /** Tear down the subscription and release the source. Idempotent. */
+    stop(): Promise<void>;
 }

package/dist/ports/observation.js

@@ -0,0 +1,7 @@
+// The observation contract — the read side shared by every ModemManager backend.
+//
+// `ModemObservationPort` is the NARROW port: it observes modems and reports them as
+// a stream of discriminated list results. It carries NO mutation methods at all.
+// The full `ModemManagerPort` (mutations) EXTENDS this, so a shadow / read-only
+// consumer can depend on observation alone and never gain a mutating verb.
+export {};