@ceralive/modem-control 0.2.0 → 1.1.0

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 {};

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>;
+}