@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/domain/observation.d.ts

@@ -0,0 +1,39 @@
+import type { Brand } from './brand.js';
+import type { DeviceGeneration } from './generation.js';
+import type { StableKey } from './physical-identity.js';
+import type { EpochMillis } from './state.js';
+export type SourceEpoch = Brand<number, 'SourceEpoch'>;
+export declare function sourceEpoch(value: number): SourceEpoch;
+export type ObservationAuthority = 'authoritative' | 'derived' | 'advisory';
+export type ObservationFreshness = {
+    readonly state: 'fresh';
+} | {
+    readonly state: 'stale';
+    readonly since: EpochMillis;
+    readonly reason: 'source-epoch-superseded' | 'ttl-expired' | 'source-degraded';
+} | {
+    readonly state: 'unavailable';
+    readonly since: EpochMillis;
+    readonly reason: 'source-unavailable' | 'device-absent' | 'provider-unavailable';
+};
+type ObservationBase = {
+    readonly stableKey: StableKey;
+    readonly generation: DeviceGeneration;
+    readonly source: string;
+    readonly sourceEpoch: SourceEpoch;
+    readonly observedAt: EpochMillis;
+    readonly authority: ObservationAuthority;
+};
+/** A value is retained while stale, but unavailable is explicit and carries no invented value. */
+export type ObservationEnvelope<T> = (ObservationBase & {
+    readonly freshness: Extract<ObservationFreshness, {
+        readonly state: 'fresh' | 'stale';
+    }>;
+    readonly value: T;
+}) | (ObservationBase & {
+    readonly freshness: Extract<ObservationFreshness, {
+        readonly state: 'unavailable';
+    }>;
+    readonly value: null;
+});
+export {};

package/dist/domain/observation.js

@@ -0,0 +1,4 @@
+import { nonNegativeInteger } from './brand.js';
+export function sourceEpoch(value) {
+    return nonNegativeInteger(value, 'sourceEpoch');
+}

package/dist/domain/operation.d.ts

@@ -0,0 +1,118 @@
+import { DomainError } from './errors.js';
+import type { DeviceGeneration } from './generation.js';
+export type OperationSupport = {
+    readonly supported: true;
+} | {
+    readonly supported: false;
+    readonly reason: string;
+};
+export type OperationConstraints<I> = {
+    readonly kind: 'unconstrained';
+} | {
+    readonly kind: 'allowed-values';
+    readonly values: readonly I[];
+} | {
+    readonly kind: 'numeric-range';
+    readonly min: number;
+    readonly max: number;
+    readonly step?: number;
+};
+export type OperationAvailability = {
+    readonly state: 'available';
+} | {
+    readonly state: 'unavailable';
+    readonly reason: string;
+} | {
+    readonly state: 'refused';
+    readonly reason: string;
+};
+export type MutationImpact = 'read' | 'write' | 'session' | 'disruptive' | 'recovery';
+export type RetryClass = 'never' | 'idempotent-read';
+export type OperationConfidence = 'high' | 'medium' | 'low' | 'unknown';
+export type OperationRequirement = {
+    readonly required: false;
+} | {
+    readonly required: true;
+    readonly reason: string;
+};
+export type OperationReadback<I, O> = {
+    readonly required: false;
+} | {
+    readonly required: true;
+    readonly reason: string;
+    readonly matches: (input: I, observed: O) => boolean;
+};
+export type OperationDescriptor<I, O> = {
+    readonly id: string;
+    readonly support: {
+        readonly read: OperationSupport;
+        readonly write: OperationSupport;
+    };
+    readonly authority: 'provider' | 'controller' | 'hardware';
+    readonly provider: string;
+    readonly constraints: OperationConstraints<I>;
+    readonly livePreconditions: readonly string[];
+    readonly availability: OperationAvailability;
+    readonly mutationImpact: MutationImpact;
+    readonly retryClass: RetryClass;
+    readonly readback: OperationReadback<I, O>;
+    readonly rollback: OperationRequirement;
+    readonly journal: OperationRequirement;
+    readonly admission: OperationRequirement;
+    readonly evidence: {
+        readonly profiles: readonly string[];
+        readonly firmware: readonly string[];
+    };
+    readonly confidence: OperationConfidence;
+};
+export declare class OperationDescriptorError extends DomainError {
+    readonly name = "OperationDescriptorError";
+    readonly reason = "retry-requires-idempotent-read";
+    constructor();
+}
+export declare function defineOperationDescriptor<I, O>(descriptor: OperationDescriptor<I, O>): OperationDescriptor<I, O>;
+export type OperationCompletion<O> = {
+    readonly status: 'applied';
+    readonly value: O;
+} | {
+    readonly status: 'refused';
+    readonly reason: string;
+} | {
+    readonly status: 'failed';
+    readonly reason: string;
+} | {
+    readonly status: 'timed-out';
+} | {
+    readonly status: 'dropped';
+};
+export type OperationResult<O> = {
+    readonly status: 'applied';
+    readonly value: O;
+    readonly generation: DeviceGeneration;
+    readonly requiresReconciliation: false;
+} | {
+    readonly status: 'refused';
+    readonly reason: string;
+    readonly generation: DeviceGeneration;
+    readonly requiresReconciliation: false;
+} | {
+    readonly status: 'unknown-outcome';
+    readonly reason: 'stale-generation' | 'write-reply-timed-out' | 'write-reply-dropped';
+    readonly generation: DeviceGeneration;
+    readonly requiresReconciliation: true;
+} | {
+    readonly status: 'failed';
+    readonly reason: string;
+    readonly generation: DeviceGeneration;
+    readonly requiresReconciliation: false;
+};
+export type OperationCompletionContext<O> = {
+    readonly operation: 'read' | 'write';
+    readonly completionGeneration: DeviceGeneration;
+    readonly currentGeneration: DeviceGeneration;
+    readonly completion: OperationCompletion<O>;
+};
+/** Apply generation and write-reply uncertainty before exposing a completion to callers. */
+export declare function classifyOperationCompletion<O>(context: OperationCompletionContext<O>): OperationResult<O>;
+/** Automatic retries are restricted to explicitly classified idempotent reads. */
+export declare function canAutoRetry<I, O>(descriptor: OperationDescriptor<I, O>, result: OperationResult<O>): boolean;

package/dist/domain/operation.js

@@ -0,0 +1,85 @@
+import { DomainError } from './errors.js';
+export class OperationDescriptorError extends DomainError {
+    name = 'OperationDescriptorError';
+    reason = 'retry-requires-idempotent-read';
+    constructor() {
+        super('operation descriptor refused: automatic retry requires a supported idempotent read');
+    }
+}
+export function defineOperationDescriptor(descriptor) {
+    if (descriptor.retryClass === 'idempotent-read' &&
+        (descriptor.mutationImpact !== 'read' || !descriptor.support.read.supported)) {
+        throw new OperationDescriptorError();
+    }
+    return descriptor;
+}
+/** Apply generation and write-reply uncertainty before exposing a completion to callers. */
+export function classifyOperationCompletion(context) {
+    const generation = context.completionGeneration;
+    if (generation !== context.currentGeneration) {
+        return {
+            status: 'unknown-outcome',
+            reason: 'stale-generation',
+            requiresReconciliation: true,
+            generation,
+        };
+    }
+    switch (context.completion.status) {
+        case 'applied':
+            return {
+                status: 'applied',
+                value: context.completion.value,
+                generation,
+                requiresReconciliation: false,
+            };
+        case 'refused':
+            return {
+                status: 'refused',
+                reason: context.completion.reason,
+                generation,
+                requiresReconciliation: false,
+            };
+        case 'failed':
+            return {
+                status: 'failed',
+                reason: context.completion.reason,
+                generation,
+                requiresReconciliation: false,
+            };
+        case 'timed-out':
+            return context.operation === 'write'
+                ? {
+                    status: 'unknown-outcome',
+                    reason: 'write-reply-timed-out',
+                    requiresReconciliation: true,
+                    generation,
+                }
+                : {
+                    status: 'failed',
+                    reason: 'read-reply-timed-out',
+                    requiresReconciliation: false,
+                    generation,
+                };
+        case 'dropped':
+            return context.operation === 'write'
+                ? {
+                    status: 'unknown-outcome',
+                    reason: 'write-reply-dropped',
+                    requiresReconciliation: true,
+                    generation,
+                }
+                : {
+                    status: 'failed',
+                    reason: 'read-reply-dropped',
+                    requiresReconciliation: false,
+                    generation,
+                };
+    }
+}
+/** Automatic retries are restricted to explicitly classified idempotent reads. */
+export function canAutoRetry(descriptor, result) {
+    return (descriptor.mutationImpact === 'read' &&
+        descriptor.support.read.supported &&
+        descriptor.retryClass === 'idempotent-read' &&
+        result.status === 'failed');
+}

package/dist/domain/physical-identity.d.ts

@@ -0,0 +1,43 @@
+import type { Brand } from './brand.js';
+import { DomainError } from './errors.js';
+export type PhysicalModemId = Brand<string, 'PhysicalModemId'>;
+export type StableKey = Brand<string, 'StableKey'>;
+export type PhysicalIdentitySource = 'serial' | 'id-path' | 'fallback';
+export type PhysicalIdentityFacts = {
+    readonly serial?: string;
+    readonly idPath?: string;
+    readonly fallback?: string;
+};
+export type ResolvedPhysicalModemIdentity = {
+    readonly physicalModemId: PhysicalModemId;
+    readonly stableKey: StableKey;
+    readonly source: PhysicalIdentitySource;
+};
+export type PhysicalModemIdentityErrorReason = 'empty' | 'unsupported-shape' | 'mm-object-path' | 'interface-name' | 'ip-address' | 'equipment-identifier' | 'subscriber-identifier' | 'fallback-too-long' | 'no-identity-facts';
+export declare class PhysicalModemIdentityError extends DomainError {
+    readonly reason: PhysicalModemIdentityErrorReason;
+    readonly name = "PhysicalModemIdentityError";
+    constructor(reason: PhysicalModemIdentityErrorReason);
+}
+/** Construct only from a canonical serial/ID_PATH/bounded-fallback identity. */
+export declare function physicalModemId(value: string): PhysicalModemId;
+/** Construct the actor/storage key for a validated physical modem identity. */
+export declare function stableKeyFromPhysicalModemId(id: PhysicalModemId): StableKey;
+/** Parse a canonical stable key while re-validating its embedded physical identity. */
+export declare function stableKey(value: string): StableKey;
+/** Resolve one identity with the frozen serial → ID_PATH → bounded-fallback precedence. */
+export declare function resolvePhysicalModemIdentity(facts: PhysicalIdentityFacts): ResolvedPhysicalModemIdentity;
+export type PortableIdentityAnchor = 'usb-serial' | 'id-path' | 'ifname';
+export interface PortablePhysicalObservation {
+    readonly ifname: string;
+    readonly idPath?: string;
+    readonly vendorId?: string;
+    readonly serial?: string;
+}
+export interface PortablePhysicalDeviceIdentity {
+    readonly identityKey: string;
+    readonly anchor: PortableIdentityAnchor;
+    readonly linkId: string;
+}
+export declare function mintLinkId(identityKey: string): string;
+export declare function resolvePortablePhysicalIdentity(observation: PortablePhysicalObservation): PortablePhysicalDeviceIdentity;

package/dist/domain/physical-identity.js

@@ -0,0 +1,113 @@
+import { createHash } from 'node:crypto';
+import { DomainError } from './errors.js';
+export class PhysicalModemIdentityError extends DomainError {
+    reason;
+    name = 'PhysicalModemIdentityError';
+    constructor(reason) {
+        super(`physical modem identity refused: ${reason}`);
+        this.reason = reason;
+    }
+}
+const PHYSICAL_ID_PREFIXES = [
+    ['serial', 'serial:'],
+    ['id-path', 'id-path:'],
+    ['fallback', 'fallback:'],
+];
+const FALLBACK_MAX_LENGTH = 128;
+const MM_OBJECT_PATH = /^\/org\/freedesktop\/ModemManager1\/Modem(?:\/|$)/;
+const INTERFACE_NAME = /^(?:wwan|eth|enp|ens|eno|wlan|wl|ppp|usb|rmnet|cdc-wdm|ttyUSB|ttyACM)\d[\w.-]*$/i;
+const EQUIPMENT_IDENTIFIER = /^\d{14,16}$/;
+const SUBSCRIBER_IDENTIFIER = /^(?:89\d{16,30}|\d{18,32})$/;
+function isIpv4(value) {
+    const octets = value.split('.');
+    return (octets.length === 4 && octets.every((octet) => /^\d{1,3}$/.test(octet) && Number(octet) <= 255));
+}
+function isIpv6(value) {
+    if (!value.includes(':') || !/^[0-9a-f:]+$/i.test(value)) {
+        return false;
+    }
+    const groups = value.split(':');
+    const hasCompression = value.includes('::');
+    const populatedGroups = groups.filter((group) => group.length > 0);
+    return (populatedGroups.every((group) => group.length <= 4) &&
+        (hasCompression ? populatedGroups.length < 8 : populatedGroups.length === 8));
+}
+function assertSafeIdentityPart(value) {
+    if (value.length === 0) {
+        throw new PhysicalModemIdentityError('empty');
+    }
+    if (MM_OBJECT_PATH.test(value)) {
+        throw new PhysicalModemIdentityError('mm-object-path');
+    }
+    if (INTERFACE_NAME.test(value)) {
+        throw new PhysicalModemIdentityError('interface-name');
+    }
+    if (isIpv4(value) || isIpv6(value)) {
+        throw new PhysicalModemIdentityError('ip-address');
+    }
+    if (SUBSCRIBER_IDENTIFIER.test(value)) {
+        throw new PhysicalModemIdentityError('subscriber-identifier');
+    }
+    if (EQUIPMENT_IDENTIFIER.test(value)) {
+        throw new PhysicalModemIdentityError('equipment-identifier');
+    }
+}
+function splitPhysicalModemId(value) {
+    for (const [source, prefix] of PHYSICAL_ID_PREFIXES) {
+        if (value.startsWith(prefix)) {
+            return [source, value.slice(prefix.length)];
+        }
+    }
+    throw new PhysicalModemIdentityError('unsupported-shape');
+}
+/** Construct only from a canonical serial/ID_PATH/bounded-fallback identity. */
+export function physicalModemId(value) {
+    const [source, identityPart] = splitPhysicalModemId(value.trim());
+    assertSafeIdentityPart(identityPart);
+    if (source === 'fallback' && identityPart.length > FALLBACK_MAX_LENGTH) {
+        throw new PhysicalModemIdentityError('fallback-too-long');
+    }
+    return `${source}:${identityPart}`;
+}
+/** Construct the actor/storage key for a validated physical modem identity. */
+export function stableKeyFromPhysicalModemId(id) {
+    return `modem:${id}`;
+}
+/** Parse a canonical stable key while re-validating its embedded physical identity. */
+export function stableKey(value) {
+    if (!value.startsWith('modem:')) {
+        throw new PhysicalModemIdentityError('unsupported-shape');
+    }
+    return stableKeyFromPhysicalModemId(physicalModemId(value.slice('modem:'.length)));
+}
+/** Resolve one identity with the frozen serial → ID_PATH → bounded-fallback precedence. */
+export function resolvePhysicalModemIdentity(facts) {
+    const candidates = [
+        ['serial', facts.serial],
+        ['id-path', facts.idPath],
+        ['fallback', facts.fallback],
+    ];
+    for (const [source, candidate] of candidates) {
+        const normalized = candidate?.trim();
+        if (normalized !== undefined && normalized.length > 0) {
+            const id = physicalModemId(`${source}:${normalized}`);
+            return { physicalModemId: id, stableKey: stableKeyFromPhysicalModemId(id), source };
+        }
+    }
+    throw new PhysicalModemIdentityError('no-identity-facts');
+}
+export function mintLinkId(identityKey) {
+    return `lnk_${createHash('sha256').update(identityKey).digest('hex').slice(0, 16)}`;
+}
+export function resolvePortablePhysicalIdentity(observation) {
+    const serial = observation.serial?.trim();
+    const idPath = observation.idPath?.trim();
+    const vendor = observation.vendorId?.trim().toLowerCase();
+    const identityKey = serial
+        ? `usb-serial:${vendor ? `${vendor}:` : ''}${serial}`
+        : idPath
+            ? `id-path:${idPath}`
+            : `ifname:${observation.ifname}`;
+    const anchor = serial ? 'usb-serial' : idPath ? 'id-path' : 'ifname';
+    return { identityKey, anchor, linkId: mintLinkId(identityKey) };
+}

package/{src/domain/policy.ts → dist/domain/policy.d.ts}

@@ -1,14 +1,5 @@
-// Durable desired-state policy — the operator's intent for one modem.
-//
-// A2.1 stubbed this shape so the domain could enforce "an ambiguous identity may
-// never bind durable policy" (see `policyBindingKey`). A2.2 owns the REAL
-// definition below: the full connection / roaming / radio / simSlot / recovery /
-// usage intent the desired-state planner reconciles (see `../ports/reconcile`).
-
-import type { EquipmentId, LogicalSlotId, ModemIdentity } from './identity';
-import { assertCanBindPolicy } from './identity';
-import type { RadioAccessTechnology } from './state';
-
+import type { EquipmentId, LogicalSlotId, ModemIdentity } from './identity.js';
+import type { RadioAccessTechnology } from './state.js';
 /**
  * The subset of identity a durable policy is allowed to key off.
  *
@@ -17,13 +8,11 @@ import type { RadioAccessTechnology } from './state';
  * anchored by the equipment id — never to a per-boot handle or a subscriber id.
  */
 export interface PolicyBindingKey {
-	readonly logicalSlotId?: LogicalSlotId;
-	readonly equipmentId: EquipmentId;
+    readonly logicalSlotId?: LogicalSlotId;
+    readonly equipmentId: EquipmentId;
 }
-
 /** IP address family a connection requests. */
 export type IpFamily = 'ipv4' | 'ipv6' | 'ipv4v6';
-
 /**
  * Connection credentials. TODAY'S SEMANTICS (draft §round-5 auth): these are
  * persisted ONLY in the NetworkManager profile; the controller keeps them
@@ -31,24 +20,22 @@ export type IpFamily = 'ipv4' | 'ipv6' | 'ipv4v6';
  * SENSITIVE and is ALWAYS redacted in logs / output / receipts (see `../redact`).
  */
 export interface DesiredAuth {
-	readonly username?: string;
-	/** SENSITIVE — always redacted; NM-profile-persisted only, transient in memory. */
-	readonly password?: string;
+    readonly username?: string;
+    /** SENSITIVE — always redacted; NM-profile-persisted only, transient in memory. */
+    readonly password?: string;
 }
-
 /** The data-connection intent. `apn: "auto"` selects NM Auto-APN (A4.1). */
 export interface DesiredConnection {
-	readonly apn: 'auto' | string;
-	readonly ipFamily: IpFamily;
-	readonly auth?: DesiredAuth;
-	/**
-	 * Manual operator selection (`gsm.network-id`) — pin registration to a specific
-	 * PLMN. Honored only while roaming (A4.1 amendment): the NM profile writes
-	 * `gsm.network-id = roaming ? networkId : ""`, so it is cleared when roaming is off.
-	 */
-	readonly networkId?: string;
+    readonly apn: 'auto' | string;
+    readonly ipFamily: IpFamily;
+    readonly auth?: DesiredAuth;
+    /**
+     * Manual operator selection (`gsm.network-id`) — pin registration to a specific
+     * PLMN. Honored only while roaming (A4.1 amendment): the NM profile writes
+     * `gsm.network-id = roaming ? networkId : ""`, so it is cleared when roaming is off.
+     */
+    readonly networkId?: string;
 }
-
 /**
  * Radio access-technology intent. `preferenceOrdered` is ranked most-preferred
  * first ("prefer 5G" ⇒ `['5gnr', 'lte', …]`); it must be honored as a PREFERENCE,
@@ -57,27 +44,24 @@ export interface DesiredConnection {
  * when present, hard-limits the technologies the modem may use at all.
  */
 export interface DesiredRadio {
-	readonly preferenceOrdered: readonly RadioAccessTechnology[];
-	readonly allowedSet?: ReadonlySet<RadioAccessTechnology>;
+    readonly preferenceOrdered: readonly RadioAccessTechnology[];
+    readonly allowedSet?: ReadonlySet<RadioAccessTechnology>;
 }
-
 /**
  * Recovery intent. DISABLED BY DEFAULT — the evidence-gated recovery ladder (A3.4)
  * adds the per-step budgets / cooldowns; in Phase A `enabled` defaults to `false`
  * and no recovery action is ever taken unless it is explicitly turned on.
  */
 export interface DesiredRecovery {
-	readonly enabled: boolean;
+    readonly enabled: boolean;
 }
-
 /** Data-usage policy — local-controller owned (see ports README ownership table). */
 export interface DesiredUsage {
-	/** Day of month (1–31) the usage cycle resets; UTC, month-length clamped (A4.3). */
-	readonly cycleDay?: number;
-	/** Advisory threshold in bytes; crossing it raises an advisory, never gates. */
-	readonly thresholdBytes?: number;
+    /** Day of month (1–31) the usage cycle resets; UTC, month-length clamped (A4.3). */
+    readonly cycleDay?: number;
+    /** Advisory threshold in bytes; crossing it raises an advisory, never gates. */
+    readonly thresholdBytes?: number;
 }
-
 /**
  * Operator-authored durable cellular policy, bound to a high/medium-confidence
  * identity via `boundTo` (a low-confidence identity cannot produce a binding key,
@@ -92,46 +76,27 @@ export interface DesiredUsage {
  *   - usage      — data-usage cycle + advisory threshold.
  */
 export interface DesiredCellularPolicy {
-	readonly boundTo: PolicyBindingKey;
-	readonly enabled: boolean;
-	readonly connection: DesiredConnection;
-	readonly roaming: boolean;
-	readonly radio: DesiredRadio;
-	readonly simSlot?: number;
-	readonly recovery: DesiredRecovery;
-	readonly usage: DesiredUsage;
+    readonly boundTo: PolicyBindingKey;
+    readonly enabled: boolean;
+    readonly connection: DesiredConnection;
+    readonly roaming: boolean;
+    readonly radio: DesiredRadio;
+    readonly simSlot?: number;
+    readonly recovery: DesiredRecovery;
+    readonly usage: DesiredUsage;
 }
-
 /** Recovery disabled — the Phase-A default (A3.4 adds budgets / cooldowns). */
-export const RECOVERY_DISABLED: DesiredRecovery = { enabled: false };
-
+export declare const RECOVERY_DISABLED: DesiredRecovery;
 /**
  * Build a sensible default policy for a bindable identity: NM activation on,
  * Auto-APN, dual-stack IP, roaming off, prefer newest RAT down to GSM, recovery
  * disabled, no usage limits. Concrete adapters and the planner refine from here.
  */
-export function defaultCellularPolicy(boundTo: PolicyBindingKey): DesiredCellularPolicy {
-	return {
-		boundTo,
-		enabled: true,
-		connection: { apn: 'auto', ipFamily: 'ipv4v6' },
-		roaming: false,
-		radio: { preferenceOrdered: ['5gnr', 'lte', 'umts', 'gsm'] },
-		recovery: RECOVERY_DISABLED,
-		usage: {},
-	};
-}
-
+export declare function defaultCellularPolicy(boundTo: PolicyBindingKey): DesiredCellularPolicy;
 /**
  * Derive the durable binding key for an identity, REFUSING low-confidence
  * (ambiguous) identities. This is the structural gate that makes it impossible to
  * bind durable policy to a duplicate/zero-IMEI modem: no key can be produced, so
  * no `DesiredCellularPolicy` can name it. Throws `PolicyBindingRefusedError`.
  */
-export function policyBindingKey(identity: ModemIdentity): PolicyBindingKey {
-	assertCanBindPolicy(identity);
-	// exactOptionalPropertyTypes: only include logicalSlotId when actually present.
-	return identity.logicalSlotId !== undefined
-		? { logicalSlotId: identity.logicalSlotId, equipmentId: identity.equipmentId }
-		: { equipmentId: identity.equipmentId };
-}
+export declare function policyBindingKey(identity: ModemIdentity): PolicyBindingKey;

package/dist/domain/policy.js

@@ -0,0 +1,38 @@
+// Durable desired-state policy — the operator's intent for one modem.
+//
+// A2.1 stubbed this shape so the domain could enforce "an ambiguous identity may
+// never bind durable policy" (see `policyBindingKey`). A2.2 owns the REAL
+// definition below: the full connection / roaming / radio / simSlot / recovery /
+// usage intent the desired-state planner reconciles (see `../ports/reconcile`).
+import { assertCanBindPolicy } from './identity.js';
+/** Recovery disabled — the Phase-A default (A3.4 adds budgets / cooldowns). */
+export const RECOVERY_DISABLED = { enabled: false };
+/**
+ * Build a sensible default policy for a bindable identity: NM activation on,
+ * Auto-APN, dual-stack IP, roaming off, prefer newest RAT down to GSM, recovery
+ * disabled, no usage limits. Concrete adapters and the planner refine from here.
+ */
+export function defaultCellularPolicy(boundTo) {
+    return {
+        boundTo,
+        enabled: true,
+        connection: { apn: 'auto', ipFamily: 'ipv4v6' },
+        roaming: false,
+        radio: { preferenceOrdered: ['5gnr', 'lte', 'umts', 'gsm'] },
+        recovery: RECOVERY_DISABLED,
+        usage: {},
+    };
+}
+/**
+ * Derive the durable binding key for an identity, REFUSING low-confidence
+ * (ambiguous) identities. This is the structural gate that makes it impossible to
+ * bind durable policy to a duplicate/zero-IMEI modem: no key can be produced, so
+ * no `DesiredCellularPolicy` can name it. Throws `PolicyBindingRefusedError`.
+ */
+export function policyBindingKey(identity) {
+    assertCanBindPolicy(identity);
+    // exactOptionalPropertyTypes: only include logicalSlotId when actually present.
+    return identity.logicalSlotId !== undefined
+        ? { logicalSlotId: identity.logicalSlotId, equipmentId: identity.equipmentId }
+        : { equipmentId: identity.equipmentId };
+}

package/dist/domain/shadow-divergence.d.ts

@@ -0,0 +1,27 @@
+export type ShadowGeneration = '2G' | '3G' | '4G' | '5G';
+export type ShadowSignalBucket = 'none' | 'poor' | 'fair' | 'good' | 'excellent';
+export interface ShadowModemState {
+    readonly deviceKey: string;
+    readonly present: boolean;
+    readonly registration?: string;
+    readonly signalBucket?: ShadowSignalBucket;
+    readonly operatorName?: string;
+    readonly simPresent?: boolean;
+    readonly networkType?: ShadowGeneration;
+}
+export declare const SHADOW_COMPARABLE_FIELDS: readonly ['present', 'registration', 'signalBucket', 'operatorName', 'simPresent', 'networkType'];
+export type ShadowComparableField = (typeof SHADOW_COMPARABLE_FIELDS)[number];
+export interface ShadowFieldDivergence {
+    readonly field: ShadowComparableField;
+    readonly mmcli: unknown;
+    readonly dbus: unknown;
+}
+export interface ShadowModemDivergence {
+    readonly deviceKey: string;
+    readonly kind: 'only-in-mmcli' | 'only-in-dbus' | 'field-mismatch';
+    readonly fields?: readonly ShadowFieldDivergence[];
+}
+export declare function classifyShadowDivergences(mmcli: readonly ShadowModemState[], dbus: readonly ShadowModemState[]): ShadowModemDivergence[];
+export declare function foldGeneration(token: string): ShadowGeneration | undefined;
+export declare function foldGenerations(tokens: Iterable<string>): ShadowGeneration | undefined;
+export declare function foldSignalBucket(quality: number | undefined): ShadowSignalBucket | undefined;