@ceralive/modem-control 0.2.0 → 1.1.0

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

@@ -0,0 +1,71 @@
+import type { DeviceGeneration } from '../../domain/index.js';
+import type { AppliedConfiguration, DesiredProfile, ModemStateView, NormalizationContext, ObservedState, StateDivergence } from '../../observations/index.js';
+import type { ConnectionId, DeviceIfname, GsmProfile, NetworkManagerPort } from '../../ports/index.js';
+import type { NmApplyResult, NmBearerState, NmDesiredRequest, NmObservationInput, NmObservationResult, NmSaveResult } from './types.js';
+export interface NetworkManagerAdapterOptions {
+    readonly port: NetworkManagerPort;
+    /** Clock for the desired/applied slots only; observations carry their own. */
+    readonly now?: () => number;
+}
+export interface NmApplyOptions {
+    readonly operationId: string;
+    readonly generation: DeviceGeneration;
+}
+export declare class NetworkManagerAdapter {
+    #private;
+    constructor(options: NetworkManagerAdapterOptions);
+    /** Every connection this adapter holds a slot for, in insertion order. */
+    trackedConnections(): readonly ConnectionId[];
+    /**
+     * Save an operator's profile and record it as DESIRED.
+     *
+     * The desired slot is built from what the caller ASKED for, not from what NM read
+     * back. That is the whole point of the slot: if NM normalized a field on the way
+     * in, the next `describeStateDivergence` is supposed to report it, and seeding
+     * desired from the readback would make that divergence structurally invisible.
+     */
+    saveDesiredProfile(request: NmDesiredRequest): Promise<NmSaveResult>;
+    /**
+     * Record that the operator wants NO bearer on this connection's device.
+     *
+     * It performs no I/O on purpose — desired is a record of intent, and the
+     * deactivation it implies happens when `applyDesired` is called, so a request and
+     * its execution stay two separately observable facts.
+     */
+    releaseDesired(id: ConnectionId, requestedBy: string): NmSaveResult;
+    desiredFor(id: ConnectionId): DesiredProfile<NmBearerState> | null;
+    /** The saved profile as NM itself holds it — a straight read, no slot involved. */
+    readSavedProfile(id: ConnectionId): Promise<GsmProfile | undefined>;
+    /**
+     * Put the desired state into force and record what was applied.
+     *
+     * The applied slot is built from the profile NM READ BACK, not from the request:
+     * "what was actually put into force" is a claim about NM's content, and asserting
+     * it from the input would make a silently-rejected field look applied.
+     */
+    applyDesired(id: ConnectionId, options: NmApplyOptions): Promise<NmApplyResult>;
+    appliedFor(id: ConnectionId): AppliedConfiguration<NmBearerState> | null;
+    /**
+     * The interface the applied bearer landed on, or `null` when no bearer is in
+     * force. An applied `unbound` state resolves to `null` rather than to its device:
+     * there is a device, but no bearer on it, and returning the name would read as one.
+     */
+    resolveAppliedInterface(id: ConnectionId): DeviceIfname | null;
+    /**
+     * Fold one complete NM readout.
+     *
+     * Never touches the desired slot. Clears the applied slot only when the readout
+     * positively contradicts it, and always says which of the four contradictions it
+     * was.
+     */
+    observe(input: NmObservationInput): NmObservationResult;
+    observedFor(id: ConnectionId): ObservedState<NmBearerState> | null;
+    /**
+     * The three-slot view. `context` supplies the provenance for the "we have not
+     * observed this yet" case — this layer has no clock or epoch counter of its own
+     * for observations, so it cannot manufacture one.
+     */
+    stateView(id: ConnectionId, context: NormalizationContext): ModemStateView<NmBearerState, NmBearerState, NmBearerState> | null;
+    /** `desiredVsApplied` ("did our write happen") and `appliedVsObserved` ("did it stick"). */
+    divergence(id: ConnectionId, context: NormalizationContext): StateDivergence | null;
+}

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

@@ -0,0 +1,348 @@
+// The thin NetworkManager adapter: desired profiles, applied bearers, and the
+// interface each one landed on — the saved-vs-applied boundary and nothing else.
+//
+// It is the ONLY bearer/APN authority surface in the package. `ModemManagerPort` has
+// no connect verb by construction (`ports/forbidden-surface.test.ts`), and the
+// ModemManager provider has no bearer operation, so nothing else can put a bearer into
+// force. Correspondingly, this adapter performs no radio, band, SIM or power operation:
+// those belong to the ModemManager provider, and expressing them here would create a
+// second writer for a resource the ownership matrix gives to exactly one.
+//
+// Two rules shape every method below.
+//
+// 1. OBSERVED STATE NEVER WRITES THE DESIRED SLOT. `observe()` may clear the applied
+//    slot and always rewrites the observed one; it does not touch `desired` on any
+//    path. Reality overtaking a write does not un-ask the question the operator asked
+//    — and if it did, a re-enumeration would silently erase the configuration the
+//    controller is supposed to restore.
+// 2. WRITES GO THROUGH THE PORT'S TYPED OPERATIONS, AND ONLY THOSE. The NM half of the
+//    port-tagged op set (`ports/ops.ts` `NmOp`) is create / update / activate /
+//    deactivate. There is deliberately no delete path here: profile removal is not in
+//    that set, so this adapter cannot express it.
+import { epochMillis } from '../../domain/index.js';
+import { appliedConfiguration, describeStateDivergence, desiredProfile, freshObservation, observedState, unavailableObservation, } from '../../observations/index.js';
+import { receipt } from '../../ports/index.js';
+import { boundBearer, nmBearerStateEquals, unboundBearer } from './types.js';
+const SOURCE = 'networkmanager';
+/** The device states in which NM is still settling an activation, not losing it. */
+const TRANSITIONAL_STATES = new Set([
+    'prepare',
+    'config',
+    'need-auth',
+    'ip-config',
+    'ip-check',
+    'secondaries',
+    'deactivating',
+]);
+export class NetworkManagerAdapter {
+    #port;
+    #now;
+    #slots = new Map();
+    #observedGeneration = null;
+    constructor(options) {
+        this.#port = options.port;
+        this.#now = options.now ?? Date.now;
+    }
+    /** Every connection this adapter holds a slot for, in insertion order. */
+    trackedConnections() {
+        return [...this.#slots.keys()];
+    }
+    // ── desired ────────────────────────────────────────────────────────────────
+    /**
+     * Save an operator's profile and record it as DESIRED.
+     *
+     * The desired slot is built from what the caller ASKED for, not from what NM read
+     * back. That is the whole point of the slot: if NM normalized a field on the way
+     * in, the next `describeStateDivergence` is supposed to report it, and seeding
+     * desired from the readback would make that divergence structurally invisible.
+     */
+    async saveDesiredProfile(request) {
+        let saved;
+        try {
+            saved =
+                request.connectionId === undefined
+                    ? await this.#port.createGsmProfile(request.profile)
+                    : await this.#port.updateGsmProfile(request.connectionId, request.profile);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                reason: 'write-failed',
+                receipt: receipt('connection', 'failed', describeError(error)),
+            };
+        }
+        const id = saved.connectionId;
+        const desired = desiredProfile(boundBearer({
+            connectionId: id,
+            deviceIfname: request.deviceIfname,
+            apn: request.profile.apn,
+            autoConfig: request.profile.autoConfig,
+            homeOnly: request.profile.homeOnly,
+        }), epochMillis(this.#now()), request.requestedBy);
+        this.#slotsFor(id).desired = desired;
+        return { ok: true, connectionId: id, desired };
+    }
+    /**
+     * Record that the operator wants NO bearer on this connection's device.
+     *
+     * It performs no I/O on purpose — desired is a record of intent, and the
+     * deactivation it implies happens when `applyDesired` is called, so a request and
+     * its execution stay two separately observable facts.
+     */
+    releaseDesired(id, requestedBy) {
+        const slots = this.#slots.get(id);
+        const ifname = slots === undefined ? undefined : targetIfname(slots);
+        if (ifname === undefined) {
+            return {
+                ok: false,
+                reason: 'no-desired-profile',
+                receipt: receipt('connection', 'failed', `no tracked device for connection ${id}`),
+            };
+        }
+        const desired = desiredProfile(unboundBearer(ifname), epochMillis(this.#now()), requestedBy);
+        this.#slotsFor(id).desired = desired;
+        return { ok: true, connectionId: id, desired };
+    }
+    desiredFor(id) {
+        return this.#slots.get(id)?.desired ?? null;
+    }
+    /** The saved profile as NM itself holds it — a straight read, no slot involved. */
+    async readSavedProfile(id) {
+        return await this.#port.readGsmProfile(id);
+    }
+    // ── applied ────────────────────────────────────────────────────────────────
+    /**
+     * Put the desired state into force and record what was applied.
+     *
+     * The applied slot is built from the profile NM READ BACK, not from the request:
+     * "what was actually put into force" is a claim about NM's content, and asserting
+     * it from the input would make a silently-rejected field look applied.
+     */
+    async applyDesired(id, options) {
+        const desired = this.desiredFor(id);
+        if (desired === null) {
+            return refuse('no-desired-profile', `connection ${id} has no desired profile`);
+        }
+        return desired.profile.kind === 'unbound'
+            ? await this.#deactivate(id, desired.profile.deviceIfname, options)
+            : await this.#activate(id, desired.profile, options);
+    }
+    appliedFor(id) {
+        return this.#slots.get(id)?.applied ?? null;
+    }
+    /**
+     * The interface the applied bearer landed on, or `null` when no bearer is in
+     * force. An applied `unbound` state resolves to `null` rather than to its device:
+     * there is a device, but no bearer on it, and returning the name would read as one.
+     */
+    resolveAppliedInterface(id) {
+        const applied = this.appliedFor(id);
+        if (applied === null || applied.configuration.kind !== 'bound') {
+            return null;
+        }
+        return applied.configuration.binding.deviceIfname;
+    }
+    // ── observed ───────────────────────────────────────────────────────────────
+    /**
+     * Fold one complete NM readout.
+     *
+     * Never touches the desired slot. Clears the applied slot only when the readout
+     * positively contradicts it, and always says which of the four contradictions it
+     * was.
+     */
+    observe(input) {
+        const generation = input.context.generation;
+        if (this.#observedGeneration !== null && generation < this.#observedGeneration) {
+            return {
+                kind: 'refused',
+                reason: 'superseded-generation',
+                currentGeneration: this.#observedGeneration,
+            };
+        }
+        this.#observedGeneration = generation;
+        const devices = new Map(input.devices.map((device) => [device.ifname, device]));
+        const outcomes = [];
+        const losses = [];
+        for (const [id, slots] of this.#slots) {
+            const ifname = targetIfname(slots);
+            if (ifname === undefined) {
+                continue;
+            }
+            const device = devices.get(ifname);
+            slots.observed = observedState(device === undefined
+                ? unavailableObservation(SOURCE, input.context, 'device-absent')
+                : freshObservation(SOURCE, input.context, observedBearer(device)));
+            const outcome = this.#classify(id, slots, ifname, device, input.context.observedAt);
+            outcomes.push({ connectionId: id, outcome });
+            if (outcome.status === 'lost') {
+                losses.push(outcome.loss);
+            }
+        }
+        return {
+            kind: 'accepted',
+            generation,
+            observedAt: input.context.observedAt,
+            outcomes,
+            losses,
+        };
+    }
+    observedFor(id) {
+        return this.#slots.get(id)?.observed ?? null;
+    }
+    /**
+     * The three-slot view. `context` supplies the provenance for the "we have not
+     * observed this yet" case — this layer has no clock or epoch counter of its own
+     * for observations, so it cannot manufacture one.
+     */
+    stateView(id, context) {
+        const slots = this.#slots.get(id);
+        if (slots === undefined) {
+            return null;
+        }
+        return {
+            desired: slots.desired,
+            applied: slots.applied,
+            observed: slots.observed ??
+                observedState(unavailableObservation(SOURCE, context, 'provider-unavailable')),
+        };
+    }
+    /** `desiredVsApplied` ("did our write happen") and `appliedVsObserved` ("did it stick"). */
+    divergence(id, context) {
+        const view = this.stateView(id, context);
+        return view === null ? null : describeStateDivergence(view, nmBearerStateEquals);
+    }
+    // ── internals ──────────────────────────────────────────────────────────────
+    async #activate(id, desired, options) {
+        if (desired.kind !== 'bound') {
+            return refuse('no-desired-profile', `connection ${id} has no bearer to activate`);
+        }
+        const ifname = desired.binding.deviceIfname;
+        const saved = await this.#port.readGsmProfile(id);
+        if (saved === undefined) {
+            return refuse('profile-absent', `connection ${id} is no longer saved in NetworkManager`);
+        }
+        let activation;
+        try {
+            activation = await this.#port.activate(id, ifname);
+        }
+        catch (error) {
+            return refuse('activation-failed', describeError(error));
+        }
+        if (activation.status !== 'applied') {
+            return { ok: false, reason: 'activation-failed', receipt: activation };
+        }
+        const applied = appliedConfiguration({
+            configuration: boundBearer({
+                connectionId: id,
+                deviceIfname: ifname,
+                apn: saved.apn,
+                autoConfig: saved.autoConfig,
+                homeOnly: saved.homeOnly,
+            }),
+            appliedAt: epochMillis(this.#now()),
+            generation: options.generation,
+            operationId: options.operationId,
+        });
+        this.#slotsFor(id).applied = applied;
+        return { ok: true, applied, receipt: activation };
+    }
+    async #deactivate(id, ifname, options) {
+        let result;
+        try {
+            result = await this.#port.deactivate(id, ifname);
+        }
+        catch (error) {
+            return refuse('deactivation-failed', describeError(error));
+        }
+        if (result.status !== 'applied') {
+            return { ok: false, reason: 'deactivation-failed', receipt: result };
+        }
+        const applied = appliedConfiguration({
+            configuration: unboundBearer(ifname),
+            appliedAt: epochMillis(this.#now()),
+            generation: options.generation,
+            operationId: options.operationId,
+        });
+        this.#slotsFor(id).applied = applied;
+        return { ok: true, applied, receipt: result };
+    }
+    #classify(id, slots, ifname, device, observedAt) {
+        const applied = slots.applied;
+        if (applied === null) {
+            return { status: 'unapplied' };
+        }
+        const lose = (reason) => {
+            slots.applied = null;
+            return {
+                status: 'lost',
+                loss: {
+                    connectionId: id,
+                    deviceIfname: ifname,
+                    reason,
+                    lostAt: observedAt,
+                    generation: applied.generation,
+                    previous: applied,
+                },
+            };
+        };
+        if (device === undefined) {
+            return lose('interface-absent');
+        }
+        if (device.state === 'failed') {
+            return lose('activation-failed');
+        }
+        if (applied.configuration.kind === 'unbound') {
+            // We deliberately took the bearer down; anything active here is somebody else.
+            return device.activeConnection === undefined
+                ? { status: 'retained', applied }
+                : lose('connection-replaced');
+        }
+        if (device.activeConnection === undefined) {
+            return lose('interface-detached');
+        }
+        if (device.activeConnection.connectionId !== id) {
+            return lose('connection-replaced');
+        }
+        if (device.state === 'activated') {
+            return { status: 'retained', applied };
+        }
+        return TRANSITIONAL_STATES.has(device.state)
+            ? { status: 'pending', applied, deviceState: device.state }
+            : lose('interface-detached');
+    }
+    #slotsFor(id) {
+        const existing = this.#slots.get(id);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const created = { desired: null, applied: null, observed: null };
+        this.#slots.set(id, created);
+        return created;
+    }
+}
+/** The device the slots are about: where the bearer IS, else where it was asked for. */
+function targetIfname(slots) {
+    const state = slots.applied?.configuration ?? slots.desired?.profile;
+    if (state === undefined) {
+        return undefined;
+    }
+    return state.kind === 'bound' ? state.binding.deviceIfname : state.deviceIfname;
+}
+function observedBearer(device) {
+    const active = device.activeConnection;
+    return active === undefined
+        ? unboundBearer(device.ifname)
+        : boundBearer({
+            connectionId: active.connectionId,
+            deviceIfname: device.ifname,
+            apn: active.apn,
+            autoConfig: active.autoConfig,
+            homeOnly: active.homeOnly,
+        });
+}
+function refuse(reason, message) {
+    return { ok: false, reason, receipt: receipt('connection', 'failed', message) };
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : 'NetworkManager rejected the request';
+}

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

@@ -0,0 +1,2 @@
+export * from './adapter.js';
+export * from './types.js';

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

@@ -0,0 +1,2 @@
+export * from './adapter.js';
+export * from './types.js';

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

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

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

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

package/dist/providers/registry.d.ts

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