@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/observations/state-separation.js

@@ -0,0 +1,52 @@
+// Desired, applied and observed are THREE things, and this module refuses to make
+// them one.
+//
+// The pattern is NetworkManager's: a connection PROFILE is what an operator asked
+// for, an active connection's BEARER is what was actually put into force, and the
+// device's own reported state is what the hardware is currently doing. All three are
+// routinely different at once — a profile edited but not re-activated, a bearer that
+// survived a profile change, a device that dropped registration without anything
+// having been re-applied — and a merged "current state" blob has to pick one of them
+// and silently lose the other two.
+//
+// Concretely, collapsing them makes these questions unanswerable:
+//   · did the operator's last change actually take effect, or is it only pending?
+//   · is what the device reports the consequence of our write, or of the network?
+//   · when a rollback is needed, what exactly do we roll back TO?
+//
+// So the three live in separate slots with separate `kind` discriminants, and the
+// comparison below reports TWO independent divergences instead of one verdict.
+// `NetworkManagerAdapter` (a later change) consumes exactly this shape.
+import { viewEnvelope } from './envelope.js';
+export function desiredProfile(profile, requestedAt, requestedBy) {
+    return { kind: 'desired', profile, requestedAt, requestedBy };
+}
+export function appliedConfiguration(input) {
+    return { kind: 'applied', ...input };
+}
+export function observedState(observation) {
+    return { kind: 'observed', observation };
+}
+export const STATE_VIEW_SLOTS = ['desired', 'applied', 'observed'];
+export function describeStateDivergence(view, equals) {
+    return {
+        desiredVsApplied: compareSlots(view.desired === null ? undefined : view.desired.profile, view.applied === null ? undefined : view.applied.configuration, view.desired === null ? 'desired' : 'applied', equals),
+        appliedVsObserved: compareSlots(view.applied === null ? undefined : view.applied.configuration, observedValue(view.observed), view.applied === null ? 'applied' : 'observed', equals),
+    };
+}
+/**
+ * The observed value, or `undefined` when the observation carries none.
+ *
+ * An unavailable observation is `indeterminate` against anything, never `aligned`:
+ * "we could not read it" is not evidence that it matches.
+ */
+function observedValue(observed) {
+    const view = viewEnvelope(observed.observation);
+    return view.kind === 'unavailable' ? undefined : view.value;
+}
+function compareSlots(left, right, missing, equals) {
+    if (left === undefined || right === undefined) {
+        return { status: 'indeterminate', missing };
+    }
+    return equals(left, right) ? { status: 'aligned' } : { status: 'diverged' };
+}

package/dist/operations/contracts.d.ts

@@ -0,0 +1,72 @@
+import type { DeviceGeneration, OperationCompletion, OperationDescriptor, OperationResult, PhysicalModemId } from '../domain/index.js';
+export type OperationPreconditionRequest = {
+    readonly operationId: string;
+    readonly physicalModemId: PhysicalModemId;
+    readonly generation: DeviceGeneration;
+    readonly descriptorId: string;
+    readonly preconditions: readonly string[];
+};
+export type OperationPreconditionResult = {
+    readonly status: 'satisfied';
+} | {
+    readonly status: 'refused';
+    readonly reason: string;
+};
+/** Live operation facts. Implementations must inspect them for every invocation. */
+export interface OperationPreconditionPort {
+    check(request: OperationPreconditionRequest): Promise<OperationPreconditionResult>;
+}
+export type OperationAttemptContext = {
+    readonly operationId: string;
+    readonly generation: DeviceGeneration;
+    readonly attempt: number;
+};
+export type OperationJournalEvent<I, O> = {
+    readonly phase: 'started';
+    readonly operationId: string;
+    readonly physicalModemId: PhysicalModemId;
+    readonly generation: DeviceGeneration;
+    readonly descriptor: OperationDescriptor<I, O>;
+    readonly input: I;
+} | {
+    readonly phase: 'completed';
+    readonly operationId: string;
+    readonly physicalModemId: PhysicalModemId;
+    readonly generation: DeviceGeneration;
+    readonly descriptor: OperationDescriptor<I, O>;
+    readonly result: OperationResult<O>;
+};
+export interface OperationJournalHook<I, O> {
+    record(event: OperationJournalEvent<I, O>): Promise<void>;
+}
+export type OperationExecution<I, O> = {
+    readonly operationId: string;
+    readonly physicalModemId: PhysicalModemId;
+    readonly descriptor: OperationDescriptor<I, O>;
+    readonly input: I;
+    readonly execute: (context: OperationAttemptContext) => Promise<OperationCompletion<O>>;
+    readonly readback?: (context: OperationAttemptContext) => Promise<OperationCompletion<O>>;
+    readonly rollback?: (context: OperationAttemptContext) => Promise<OperationCompletion<void>>;
+    readonly journal?: OperationJournalHook<I, O>;
+};
+export type ReconciliationExecution = {
+    readonly physicalModemId: PhysicalModemId;
+    readonly generation: DeviceGeneration;
+    readonly run: () => Promise<{
+        readonly status: 'reconciled';
+    } | {
+        readonly status: 'failed';
+        readonly reason: string;
+    }>;
+};
+export type ReconciliationResult = {
+    readonly status: 'reconciled';
+    readonly generation: DeviceGeneration;
+} | {
+    readonly status: 'not-required';
+    readonly generation: DeviceGeneration;
+} | {
+    readonly status: 'failed';
+    readonly reason: 'stale-generation' | string;
+    readonly generation: DeviceGeneration;
+};

package/dist/operations/contracts.js

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

package/dist/operations/index.d.ts

@@ -0,0 +1 @@
+export * from './operation-engine.js';

package/dist/operations/index.js

@@ -0,0 +1 @@
+export * from './operation-engine.js';

package/dist/operations/operation-engine.d.ts

@@ -0,0 +1,16 @@
+import { type DeviceGeneration, type OperationResult, type PhysicalModemId } from '../domain/index.js';
+import type { ModemControlCompositionRoot } from '../safety/index.js';
+import type { OperationExecution, OperationPreconditionPort, ReconciliationExecution, ReconciliationResult } from './contracts.js';
+export * from './contracts.js';
+export type OperationEngineOptions = {
+    readonly root: ModemControlCompositionRoot;
+    readonly currentGeneration: (physicalModemId: PhysicalModemId) => DeviceGeneration;
+    readonly preconditions: OperationPreconditionPort;
+};
+export declare class OperationEngine {
+    #private;
+    constructor(options: OperationEngineOptions);
+    invoke<I, O>(execution: OperationExecution<I, O>): Promise<OperationResult<O>>;
+    reconcile(execution: ReconciliationExecution): Promise<ReconciliationResult>;
+}
+export declare function createOperationEngine(options: OperationEngineOptions): OperationEngine;

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