@ceralive/modem-control 0.1.0

package/src/domain/state.ts

@@ -0,0 +1,189 @@
+// Orthogonal state dimensions.
+//
+// Draft §Oracle round-1: modem state is NOT one enum. It is a set of independent
+// dimensions that vary separately — presence, SIM, radio, registration,
+// NM-activation, data interface, reconcile, recovery. Collapsing them into a
+// single enum loses real, simultaneously-true facts (e.g. "present + radio on +
+// searching + no NM connection"). Each dimension below mirrors a real
+// ModemManager / NetworkManager concept; values track those enums.
+
+import type { Brand } from './brand';
+import { nonNegativeInteger } from './brand';
+
+/** Milliseconds since the Unix epoch. */
+export type EpochMillis = Brand<number, 'EpochMillis'>;
+
+/** Construct an `EpochMillis` from a non-negative integer timestamp. */
+export function epochMillis(value: number): EpochMillis {
+	return nonNegativeInteger(value, 'epochMillis') as EpochMillis;
+}
+
+// --- 1. presence + source health -------------------------------------------
+
+/** Whether the modem is in the current authoritative observation snapshot. */
+export type Presence = 'present' | 'absent';
+
+/**
+ * Health of the observation SOURCE (the ModemManager daemon / bus), independent
+ * of presence. When the source drops (owner loss, bus disconnect) the last data
+ * goes `stale` and then `sourceUnavailable` — it is NEVER silently turned into
+ * `absent`. Only an authoritative snapshot confirms real removal (A3.1 epochs).
+ */
+export type SourceHealth = 'live' | 'stale' | 'sourceUnavailable';
+
+// --- 2. SIM slots + lock ----------------------------------------------------
+
+/** SIM lock state — subset of `MMModemLock` plus `unknown`. */
+export type SimLock =
+	| 'unknown'
+	| 'none'
+	| 'sim-pin'
+	| 'sim-puk'
+	| 'sim-pin2'
+	| 'sim-puk2'
+	| 'net-pers'
+	| 'permanently-blocked';
+
+/** A single physical SIM slot. */
+export interface SimSlot {
+	/** 1-based slot index (ModemManager numbers slots from 1). */
+	readonly index: number;
+	/** A SIM card is physically inserted in this slot. */
+	readonly occupied: boolean;
+	/** This is the primary/active slot the modem is currently using. */
+	readonly active: boolean;
+	readonly lock: SimLock;
+}
+
+/** Lock states that require a SIM to actually be present in the slot. */
+export const SIM_LOCK_REQUIRES_CARD: ReadonlySet<SimLock> = new Set<SimLock>([
+	'sim-pin',
+	'sim-puk',
+	'sim-pin2',
+	'sim-puk2',
+	'net-pers',
+	'permanently-blocked',
+]);
+
+// --- 3. radio power + MM state ---------------------------------------------
+
+/** Radio power state — `MMModemPowerState`. */
+export type RadioPower = 'unknown' | 'off' | 'low' | 'on';
+
+/** Modem lifecycle state — `MMModemState`. */
+export type MmState =
+	| 'failed'
+	| 'unknown'
+	| 'initializing'
+	| 'locked'
+	| 'disabled'
+	| 'disabling'
+	| 'enabling'
+	| 'enabled'
+	| 'searching'
+	| 'registered'
+	| 'disconnecting'
+	| 'connecting'
+	| 'connected';
+
+/**
+ * MM states that imply the radio is powered and actively on the air — none of
+ * these can coexist with `radioPower: 'off'`, and all imply the modem is present.
+ */
+export const MM_STATES_REQUIRING_RADIO: ReadonlySet<MmState> = new Set<MmState>([
+	'enabled',
+	'searching',
+	'registered',
+	'connecting',
+	'connected',
+	'disconnecting',
+]);
+
+// --- 4. registration + RAT set ---------------------------------------------
+
+/** 3GPP registration state — `MMModem3gppRegistrationState`. */
+export type RegistrationStatus = 'idle' | 'home' | 'searching' | 'denied' | 'unknown' | 'roaming';
+
+/** Radio access technology family — subset of `MMModemAccessTechnology` groups. */
+export type RadioAccessTechnology = 'gsm' | 'umts' | 'lte' | '5gnr';
+
+/**
+ * Registration dimension: a status plus the SET of currently-active access
+ * technologies. MM's access-technology field is a bitmask (carrier aggregation
+ * can light more than one), so a set — not a single value — is the faithful model.
+ */
+export interface Registration {
+	readonly status: RegistrationStatus;
+	readonly activeRats: ReadonlySet<RadioAccessTechnology>;
+}
+
+/** Registration statuses that mean the modem is attached to a network. */
+export function isRegistered(status: RegistrationStatus): boolean {
+	return status === 'home' || status === 'roaming';
+}
+
+// --- 5. NM activation -------------------------------------------------------
+
+/**
+ * NetworkManager connection/activation state for this modem's device — `NMDeviceState`
+ * collapsed to the states that matter. NM is the SOLE owner of activation; this
+ * dimension reflects, never drives, that ownership.
+ */
+export type NmActivation =
+	| 'unmanaged'
+	| 'unavailable'
+	| 'disconnected'
+	| 'activating'
+	| 'activated'
+	| 'deactivating'
+	| 'failed';
+
+// --- 6. data interface ------------------------------------------------------
+
+/**
+ * The net device the modem exposes for data (e.g. `wwan0`). `name` may be absent
+ * even when `present` (MM can report a bearer whose ip-interface is not yet
+ * named); a `name` without `present` is impossible and guarded.
+ */
+export interface DataInterface {
+	readonly present: boolean;
+	readonly name?: string;
+}
+
+// --- 7. reconcile status ----------------------------------------------------
+
+/**
+ * Aggregate desired-state reconciliation status. Mirrors the A2.2 receipt
+ * taxonomy at snapshot granularity: `unsupported` means the desired state cannot
+ * be applied on this hardware (e.g. "prefer 5G" on a 4G-only modem) — surfaced,
+ * never silently dropped.
+ */
+export type ReconcileStatus = 'converged' | 'reconciling' | 'pending' | 'divergent' | 'unsupported';
+
+// --- 8. recovery state ------------------------------------------------------
+
+/**
+ * Recovery-ladder stage. Ordered rungs mirror A3.4:
+ *   nm-cycle → mm-cycle → reset → power-cycle, gated by attribution and budgets.
+ * `idle` = nothing in flight; `exhausted` = budget spent, gave up.
+ */
+export type RecoveryStage =
+	| 'idle'
+	| 'attributing'
+	| 'nm-cycle'
+	| 'mm-cycle'
+	| 'reset'
+	| 'power-cycle'
+	| 'cooldown'
+	| 'exhausted';
+
+/**
+ * Recovery dimension. `cooldownUntil` is present ONLY while `stage` is `cooldown`
+ * (guarded); `attempts` counts disruptive rungs fired in the current budget window
+ * and resets to 0 at `idle`.
+ */
+export interface RecoveryState {
+	readonly stage: RecoveryStage;
+	readonly attempts: number;
+	readonly cooldownUntil?: EpochMillis;
+}

package/src/index.test.ts

@@ -0,0 +1,6 @@
+import { expect, test } from 'bun:test';
+import { PACKAGE_NAME } from './index';
+
+test('control package exposes its name', () => {
+	expect(PACKAGE_NAME).toBe('@ceralive/modem-control');
+});

package/src/index.ts

@@ -0,0 +1,15 @@
+// @ceralive/modem-control — package entry point.
+//
+// Phase A: the domain model (identity + orthogonal state + revisions) under
+// `./domain`, the MM / NM / Router port contracts + desired-state planner under
+// `./ports`, the redaction module (`./redact`), and the epoch-scoped ModemManager
+// D-Bus observer under `./backend`. The NetworkManager adapter, USB composition-mode
+// model, and data-usage sampler land in later waves.
+
+export const PACKAGE_NAME = '@ceralive/modem-control';
+
+export * from './backend';
+export * from './domain';
+export * from './ports';
+export * from './redact';
+export * from './usb-mode';

package/src/ports/README.md

@@ -0,0 +1,61 @@
+# Port contracts + ownership matrix
+
+The adapter boundaries `@ceralive/modem-control` reconciles across. Every concrete
+backend — the A2.3 fake harness, the A3.x ModemManager D-Bus backend, the A4.1
+`nmcli` NetworkManager adapter — implements one of these interfaces. Nothing here
+performs I/O; these are pure TypeScript contracts.
+
+## The ports
+
+| Port | File | Responsibility |
+|------|------|----------------|
+| `ModemObservationPort` | [`observation.ts`](./observation.ts) | Read-only: `start()`, `observe()`, `stop()`; emits discriminated `ObservationList` results that **retain rows** on source failure (removal is only ever an authoritative snapshot omission). |
+| `ModemManagerPort` | [`modem-manager.ts`](./modem-manager.ts) | **Extends** the observation port with the mutations MM owns: `setRadioModes`, `setPrimarySimSlot`, `sendPin`/`sendPuk`, `scanNetworks`, `inhibit`/`uninhibit`. **NO bearer/connect verb.** |
+| `NetworkManagerPort` | [`network-manager.ts`](./network-manager.ts) | GSM profile CRUD; `activate`/`deactivate` taking **both** `(connectionId, deviceIfname)`; quiesce lease. |
+| `RouterPort` | [`router.ts`](./router.ts) | Presence + advisory health only, for devices MM cannot control. |
+
+## Ownership matrix — one sole writer per resource
+
+Each resource below has **exactly one** owner. No other component writes it. This is
+the NM-owns-bearers architecture the whole package is built around (independent
+review correction, draft §Oracle #1): the controller is a reconciler over two
+adapters, never a second writer of the same resource.
+
+| Resource | Sole writer | Port / owner |
+|----------|-------------|--------------|
+| APN | NetworkManager | `NetworkManagerPort` (`gsm.apn` / auto-config) |
+| Connection auth (username / password) | NetworkManager | `NetworkManagerPort` (`gsm.username` / `gsm.password`) |
+| Roaming | NetworkManager | `NetworkManagerPort` (`gsm.home-only`) |
+| Autoconnect | NetworkManager | `NetworkManagerPort` (`connection.autoconnect`) |
+| Activation (bearer lifecycle) | NetworkManager | `NetworkManagerPort` (`activate`/`deactivate`) |
+| Radio access-technology modes | ModemManager | `ModemManagerPort.setRadioModes` |
+| SIM operations (PIN / PUK / primary slot / scan) | ModemManager | `ModemManagerPort` |
+| Recovery ladder | Local controller | policy `recovery` (disabled by default, A3.4) |
+| Usage policy (cycle / threshold) | Local controller | policy `usage` (A4.3 sampler) |
+
+### The bearer invariant (safety-critical)
+
+**The controller NEVER calls MM's `Simple.Connect`, `CreateBearer`, or
+`Bearer.Connect`.** Bearers, APN, and connection activation belong exclusively to
+NetworkManager. `ModemManagerPort` therefore has no `connect`, `createBearer`, or
+`bearerConnect` method, and none may ever be added. This is enforced at build time
+by [`forbidden-surface.test.ts`](./forbidden-surface.test.ts), which scans every
+port source file and fails if any bearer/connect method declaration appears.
+
+## Port-tagged ops
+
+The planner ([`reconcile.ts`](./reconcile.ts)) emits **port-tagged ops**
+([`ops.ts`](./ops.ts)): a discriminated union `{ port: 'mm', op: MmOp } | { port:
+'nm', op: NmOp }` whose op-kind spaces are disjoint. A radio op tagged for the NM
+port — `{ port: 'nm', op: { kind: 'setRadioModes', … } }` — is a **compile-time type
+error**, proved by [`ops.type-test.ts`](./ops.type-test.ts) (`@ts-expect-error`
+lines that `tsc --noEmit` must flag). The ownership matrix is thus enforced by the
+type system, not merely by convention.
+
+## Receipts
+
+Reconciliation is honest: each policy dimension yields exactly one
+[`Receipt`](./receipts.ts) with a status (`applied | pending | unsupported |
+failed`) and a **reason**. Nothing is silently dropped — "prefer 5G" on a 4G-only
+modem returns `unsupported` with an explicit reason, never a quiet downgrade to a
+4G-only mode.

package/src/ports/forbidden-surface.test.ts

@@ -0,0 +1,80 @@
+// Guard: no port interface may ever declare a bearer / connect method.
+//
+// The single most safety-critical constraint in the package (Must-NOT-Have: "no MM
+// Simple.Connect / CreateBearer / Bearer.Connect calls ever"). Interfaces are
+// erased at runtime, so the enforcement is a source scan: every port `.ts` file is
+// stripped of comments (so prose mentions of "bearer" never trip it) and checked
+// for a method declaration whose name is `connect`, `simpleConnect`, or contains
+// "bearer". Adding such a method to any port fails this test — and therefore CI.
+
+import { expect, test } from 'bun:test';
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const portsDir = import.meta.dir;
+
+function isForbiddenMethodName(name: string): boolean {
+	const lower = name.toLowerCase();
+	return lower === 'connect' || lower === 'simpleconnect' || lower.includes('bearer');
+}
+
+function stripComments(source: string): string {
+	return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+}
+
+function declaredMemberNames(source: string): string[] {
+	const names: string[] = [];
+	const methodDecl = /(?:^|\n)\s*([a-zA-Z_$][\w$]*)\s*[<(]/g;
+	let match = methodDecl.exec(source);
+	while (match !== null) {
+		const name = match[1];
+		if (name !== undefined) {
+			names.push(name);
+		}
+		match = methodDecl.exec(source);
+	}
+	return names;
+}
+
+function portSourceFiles(): string[] {
+	return readdirSync(portsDir)
+		.filter((file) => file.endsWith('.ts'))
+		.filter((file) => !file.endsWith('.test.ts') && !file.endsWith('.type-test.ts'));
+}
+
+test('no port source declares a bearer / connect method', async () => {
+	for (const file of portSourceFiles()) {
+		const source = stripComments(await Bun.file(join(portsDir, file)).text());
+		const forbidden = declaredMemberNames(source).filter(isForbiddenMethodName);
+		expect(forbidden, `forbidden method(s) in ${file}: ${forbidden.join(', ')}`).toEqual([]);
+	}
+});
+
+test('the ModemManager port source declares the expected non-bearer mutations', async () => {
+	const source = stripComments(await Bun.file(join(portsDir, 'modem-manager.ts')).text());
+	const names = declaredMemberNames(source);
+	for (const expected of [
+		'setRadioModes',
+		'setPrimarySimSlot',
+		'sendPin',
+		'sendPuk',
+		'scanNetworks',
+		'inhibit',
+		'uninhibit',
+	]) {
+		expect(names).toContain(expected);
+	}
+});
+
+test('the detector actually catches a bearer / connect method (self-test)', () => {
+	const rogue = `
+		export interface Rogue {
+			connect(): Promise<void>;
+			createBearer(): Promise<void>;
+			bearerConnect(): Promise<void>;
+			setRadioModes(): Promise<void>;
+		}
+	`;
+	const flagged = declaredMemberNames(stripComments(rogue)).filter(isForbiddenMethodName).sort();
+	expect(flagged).toEqual(['bearerConnect', 'connect', 'createBearer']);
+});

package/src/ports/index.ts

@@ -0,0 +1,16 @@
+// Port contracts — the MM / NM / Router adapter boundaries plus the desired-state
+// planner and receipts. Concrete backends (A2.3 fake, A3.x D-Bus, A4.1 nmcli)
+// implement these interfaces; nothing here performs I/O.
+//
+// OWNERSHIP MATRIX (see ./README.md): NM owns bearers / APN / auth / roaming /
+// 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';

package/src/ports/modem-manager.ts

@@ -0,0 +1,72 @@
+// 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.
+
+import type { DesiredRadio, EpochMillis, RuntimePath } from '../domain';
+import type { ModemObservationPort } from './observation';
+import type { Receipt } from './receipts';
+
+/** 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 };
+
+/** 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 ModemManagerPort extends ModemObservationPort {
+	/** Set the modem's radio access-technology preference. */
+	setRadioModes(modem: ModemRef, preference: DesiredRadio): 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>;
+	/** 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>;
+}

package/src/ports/network-manager.ts

@@ -0,0 +1,87 @@
+// 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 type { Brand, EpochMillis } from '../domain';
+import { nonEmptyString } from '../domain';
+import type { Receipt } from './receipts';
+
+/** 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 function connectionId(value: string): ConnectionId {
+	return nonEmptyString(value, 'connectionId') as ConnectionId;
+}
+
+/** Construct a `DeviceIfname` from a non-empty interface name. */
+export function deviceIfname(value: string): DeviceIfname {
+	return nonEmptyString(value, 'deviceIfname') as 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/src/ports/observation.ts

@@ -0,0 +1,48 @@
+// 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';
+
+/** 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
+ * a source drop can never be mistaken for a removal. Real removal is only ever
+ * 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[];
+	  };
+
+/** 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
+ * carrying a monotonic revision); `stop()` tears the subscription down. No method
+ * 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>;
+}

package/src/ports/ops.ts

@@ -0,0 +1,60 @@
+// 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.
+
+import type { DesiredRadio } from '../domain';
+import type {
+	ConnectionId,
+	DeviceIfname,
+	GsmProfileInput,
+	GsmProfilePatch,
+} from './network-manager';
+
+/** 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 function mmOp(op: MmOp): PortTaggedOp {
+	return { port: 'mm', op };
+}
+
+/** Tag an NM op for the NetworkManager port. Only an `NmOp` is accepted. */
+export function nmOp(op: NmOp): PortTaggedOp {
+	return { port: 'nm', op };
+}