@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/domain/snapshot.d.ts

@@ -0,0 +1,53 @@
+import type { Brand } from './brand.js';
+import type { ModemIdentity } from './identity.js';
+import type { DataInterface, MmState, NmActivation, Presence, RadioPower, ReconcileStatus, RecoveryState, Registration, SimSlot, SourceHealth } from './state.js';
+/** A monotonically increasing snapshot revision. */
+export type Revision = Brand<number, 'Revision'>;
+/** Construct a `Revision` from a non-negative integer. */
+export declare function revision(value: number): Revision;
+/** The revision every fresh identity starts at. */
+export declare const INITIAL_REVISION: Revision;
+/** The next revision after `current`. */
+export declare function nextRevision(current: Revision): Revision;
+/** The full coherent state of one modem at one point in time. */
+export interface CellularSnapshot {
+    readonly identity: ModemIdentity;
+    readonly presence: Presence;
+    readonly sourceHealth: SourceHealth;
+    readonly simSlots: readonly SimSlot[];
+    readonly radioPower: RadioPower;
+    readonly mmState: MmState;
+    readonly registration: Registration;
+    readonly nmActivation: NmActivation;
+    readonly dataInterface: DataInterface;
+    readonly reconcileStatus: ReconcileStatus;
+    readonly recoveryState: RecoveryState;
+    readonly revision: Revision;
+}
+/** A partial update to a snapshot's dimensions; `revision` is managed, not patched. */
+export type SnapshotPatch = Partial<Omit<CellularSnapshot, 'revision'>>;
+/**
+ * Validate and return a snapshot. The guards run here: an impossible combination
+ * throws `ImpossibleStateError` rather than producing an incoherent value. This
+ * is the sole sanctioned constructor for an arbitrary snapshot.
+ */
+export declare function createSnapshot(fields: CellularSnapshot): CellularSnapshot;
+/** A valid baseline for a freshly-observed-but-absent modem, at revision 0. */
+export declare function initialSnapshot(identity: ModemIdentity): CellularSnapshot;
+/**
+ * Apply a dimension patch, bump the revision, and re-validate. Monotonicity is
+ * automatic (revision always advances by one); an impossible result throws.
+ */
+export declare function applyTransition(prev: CellularSnapshot, patch: SnapshotPatch): CellularSnapshot;
+/**
+ * Replace a snapshot with a fully-formed successor that carries its own revision
+ * (the observer path). Enforces strict monotonicity — a stale or equal revision
+ * throws `RevisionMonotonicityError` — and validates the successor.
+ */
+export declare function supersede(prev: CellularSnapshot, next: CellularSnapshot): CellularSnapshot;
+/**
+ * The source (MM daemon / bus) dropped: mark the data `sourceUnavailable` while
+ * KEEPING presence and all other facts. Stale is never removal — only an
+ * authoritative snapshot confirms absence (draft §Oracle round-1 lifecycle).
+ */
+export declare function markSourceUnavailable(prev: CellularSnapshot): CellularSnapshot;

package/dist/domain/snapshot.js

@@ -0,0 +1,75 @@
+// CellularSnapshot — the whole coherent state of one modem at one revision.
+//
+// A snapshot composes the identity and all eight orthogonal dimensions plus a
+// monotonic `revision`. Every snapshot that exists has passed the guards: the
+// constructors here are the ONLY sanctioned way to build or advance one, so an
+// impossible combination can never be observed downstream. Revisions strictly
+// increase, letting the observer (A3.1) and consumers order and dedupe events.
+import { nonNegativeInteger } from './brand.js';
+import { RevisionMonotonicityError } from './errors.js';
+import { assertSnapshot } from './guards.js';
+/** Construct a `Revision` from a non-negative integer. */
+export function revision(value) {
+    return nonNegativeInteger(value, 'revision');
+}
+/** The revision every fresh identity starts at. */
+export const INITIAL_REVISION = revision(0);
+/** The next revision after `current`. */
+export function nextRevision(current) {
+    return (current + 1);
+}
+/**
+ * Validate and return a snapshot. The guards run here: an impossible combination
+ * throws `ImpossibleStateError` rather than producing an incoherent value. This
+ * is the sole sanctioned constructor for an arbitrary snapshot.
+ */
+export function createSnapshot(fields) {
+    assertSnapshot(fields);
+    return fields;
+}
+/** A valid baseline for a freshly-observed-but-absent modem, at revision 0. */
+export function initialSnapshot(identity) {
+    return {
+        identity,
+        presence: 'absent',
+        sourceHealth: 'live',
+        simSlots: [],
+        radioPower: 'unknown',
+        mmState: 'unknown',
+        registration: { status: 'unknown', activeRats: new Set() },
+        nmActivation: 'unavailable',
+        dataInterface: { present: false },
+        reconcileStatus: 'pending',
+        recoveryState: { stage: 'idle', attempts: 0 },
+        revision: INITIAL_REVISION,
+    };
+}
+/**
+ * Apply a dimension patch, bump the revision, and re-validate. Monotonicity is
+ * automatic (revision always advances by one); an impossible result throws.
+ */
+export function applyTransition(prev, patch) {
+    const next = { ...prev, ...patch, revision: nextRevision(prev.revision) };
+    assertSnapshot(next);
+    return next;
+}
+/**
+ * Replace a snapshot with a fully-formed successor that carries its own revision
+ * (the observer path). Enforces strict monotonicity — a stale or equal revision
+ * throws `RevisionMonotonicityError` — and validates the successor.
+ */
+export function supersede(prev, next) {
+    if (next.revision <= prev.revision) {
+        throw new RevisionMonotonicityError(prev.revision, next.revision);
+    }
+    assertSnapshot(next);
+    return next;
+}
+/**
+ * The source (MM daemon / bus) dropped: mark the data `sourceUnavailable` while
+ * KEEPING presence and all other facts. Stale is never removal — only an
+ * authoritative snapshot confirms absence (draft §Oracle round-1 lifecycle).
+ */
+export function markSourceUnavailable(prev) {
+    return applyTransition(prev, { sourceHealth: 'sourceUnavailable' });
+}

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

@@ -1,28 +1,10 @@
-// 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';
-
+import type { Brand } from './brand.js';
 /** 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 -------------------------------------------
-
+export declare function epochMillis(value: number): EpochMillis;
 /** 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
@@ -30,128 +12,59 @@ export type Presence = 'present' | 'absent';
  * `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';
-
+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;
+    /** 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 ---------------------------------------------
-
+export declare const SIM_LOCK_REQUIRES_CARD: ReadonlySet<SimLock>;
 /** 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';
-
+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 ---------------------------------------------
-
+export declare const MM_STATES_REQUIRING_RADIO: ReadonlySet<MmState>;
 /** 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>;
+    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 -------------------------------------------------------
-
+export declare function isRegistered(status: RegistrationStatus): boolean;
 /**
  * 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 ------------------------------------------------------
-
+export type NmActivation = 'unmanaged' | 'unavailable' | 'disconnected' | 'activating' | 'activated' | 'deactivating' | 'failed';
 /**
  * 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;
+    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
@@ -159,31 +72,19 @@ export interface DataInterface {
  * 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';
-
+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;
+    readonly stage: RecoveryStage;
+    readonly attempts: number;
+    readonly cooldownUntil?: EpochMillis;
 }

package/dist/domain/state.js

@@ -0,0 +1,38 @@
+// 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 { nonNegativeInteger } from './brand.js';
+/** Construct an `EpochMillis` from a non-negative integer timestamp. */
+export function epochMillis(value) {
+    return nonNegativeInteger(value, 'epochMillis');
+}
+/** Lock states that require a SIM to actually be present in the slot. */
+export const SIM_LOCK_REQUIRES_CARD = new Set([
+    'sim-pin',
+    'sim-puk',
+    'sim-pin2',
+    'sim-puk2',
+    'net-pers',
+    'permanently-blocked',
+]);
+/**
+ * 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 = new Set([
+    'enabled',
+    'searching',
+    'registered',
+    'connecting',
+    'connected',
+    'disconnecting',
+]);
+/** Registration statuses that mean the modem is attached to a network. */
+export function isRegistered(status) {
+    return status === 'home' || status === 'roaming';
+}

package/dist/fcc/coverage.d.ts

@@ -0,0 +1,63 @@
+/** The four vendor scripts ModemManager 1.24.2 ships, and what each one drives. */
+export declare const MM_FCC_UNLOCK_VENDOR_SCRIPTS: {
+    readonly '105b': "mbimcli";
+    readonly '1199': "qmicli";
+    readonly '14c3': "mbimcli";
+    readonly '2c7c': "qmicli";
+};
+export type MmFccUnlockVendorScript = keyof typeof MM_FCC_UNLOCK_VENDOR_SCRIPTS;
+/** The interpreters those scripts invoke, and the packages that provide them. */
+export declare const MM_FCC_UNLOCK_RUNTIME_PACKAGES: {
+    readonly qmicli: "libqmi-utils";
+    readonly mbimcli: "libmbim-utils";
+};
+/**
+ * ModemManager 1.24.2's COMPLETE shipped mapping — `data/dispatcher-fcc-unlock/
+ * meson.build`'s `vidpids` dict, verbatim. Fourteen entries; there are no others.
+ */
+export declare const MM_FCC_UNLOCK_COVERAGE: {
+    readonly '03f0:4e1d': "1199";
+    readonly '105b:e0ab': "105b";
+    readonly '105b:e0c3': "105b";
+    readonly '1199:9079': "1199";
+    readonly '14c3:4d75': "14c3";
+    readonly '1eac:1001': "2c7c";
+    readonly '1eac:1004': "2c7c";
+    readonly '1eac:1007': "2c7c";
+    readonly '2c7c:030a': "2c7c";
+    readonly '2c7c:0313': "2c7c";
+    readonly '2c7c:0314': "2c7c";
+    readonly '2c7c:0801': "2c7c";
+    readonly '413c:81a3': "1199";
+    readonly '413c:81a8': "1199";
+};
+export type MmFccUnlockKey = keyof typeof MM_FCC_UNLOCK_COVERAGE;
+/**
+ * Fold a vid/pid pair into the dispatcher's key, or `undefined` when it is not a
+ * pair of 4-hex ids. Case is folded because sysfs and udev disagree about it
+ * (`ID_VENDOR_ID` is lowercase, some vendor strings are not) while the dispatcher's
+ * `%04x` is unambiguously lowercase; a `0x` prefix is tolerated for the same reason.
+ * NOTHING ELSE is normalized — a 3-digit or 5-digit id is a different device, not a
+ * sloppy spelling of this one.
+ */
+export declare function normalizeVidPid(vid: string, pid: string): string | undefined;
+/** True for a string already in the dispatcher's `<vid>:<pid>` shape. */
+export declare function isFccUnlockKey(value: string): boolean;
+/**
+ * Does ModemManager ship an unlock procedure for this device?
+ *
+ * The three answers are NOT interchangeable, and the third is why this returns a
+ * tri-state rather than a boolean:
+ *   present — a `<vid>:<pid>` entry exists; the toggle can do something.
+ *   absent  — the ids are well-formed and are NOT in the mapping. A positive
+ *             statement about the device, so the module reads `unavailable` and no
+ *             control is offered.
+ *   unknown — we could not read the ids at all. That is a statement about the READ,
+ *             and reporting it as `absent` would hide the module on hardware that
+ *             may well be covered.
+ */
+export declare function resolveFccUnlockCoverage(vid: string | undefined, pid: string | undefined): 'present' | 'absent' | 'unknown';
+/** The vendor script a covered key resolves to, for diagnostics and docs. */
+export declare function fccUnlockVendorScript(key: string): MmFccUnlockVendorScript | undefined;
+/** The interpreter a covered key's script invokes (`qmicli` / `mbimcli`). */
+export declare function fccUnlockRuntimeBinary(key: string): 'qmicli' | 'mbimcli' | undefined;

package/dist/fcc/coverage.js

@@ -0,0 +1,102 @@
+// The FCC-unlock COVERAGE CATALOG — which `<vid>:<pid>` ModemManager can unlock.
+//
+// This is the evidence source for the `fcc-auto-unlock` capability module.
+// `capability/detect.ts` answers `unknown` for that module on purpose and says why:
+// FCC unlock is carried out by a ModemManager DISPATCHER keyed on the device, and
+// nothing on the modem's own D-Bus surface says whether a procedure applies. So the
+// answer has to come from a catalog, and this is it.
+//
+// Pinned to ModemManager 1.24.2 (`packaging/upstream-pins.yaml`) — the exact release
+// this repository rebuilds. Prose walkthrough, per-device fleet verdicts and the
+// market table: `docs/FCC-UNLOCK-COVERAGE.md`.
+//
+// THE KEY IS `<vid>:<pid>` AND NOTHING ELSE. `mm-dispatcher-fcc-unlock.c` builds
+// exactly one filename — `g_strdup_printf("%04x:%04x", vid, pid)` — and looks for it
+// in the two enabled tiers. A vendor-only name is never opened by the dispatcher; it
+// only ever exists as the TARGET of a `<vid>:<pid>` link in the available tier. And a
+// vendor-keyed rule would be wrong twice over: Sierra silicon ships under three
+// vendor ids (`1199` its own, `03f0` HP-branded, `413c` Dell-branded), so keying on
+// the vendor misses two of the three, while keying on the model misses the rebrands.
+/** The four vendor scripts ModemManager 1.24.2 ships, and what each one drives. */
+export const MM_FCC_UNLOCK_VENDOR_SCRIPTS = {
+    '105b': 'mbimcli',
+    '1199': 'qmicli',
+    '14c3': 'mbimcli',
+    '2c7c': 'qmicli',
+};
+/** The interpreters those scripts invoke, and the packages that provide them. */
+export const MM_FCC_UNLOCK_RUNTIME_PACKAGES = {
+    qmicli: 'libqmi-utils',
+    mbimcli: 'libmbim-utils',
+};
+/**
+ * ModemManager 1.24.2's COMPLETE shipped mapping — `data/dispatcher-fcc-unlock/
+ * meson.build`'s `vidpids` dict, verbatim. Fourteen entries; there are no others.
+ */
+export const MM_FCC_UNLOCK_COVERAGE = {
+    '03f0:4e1d': '1199',
+    '105b:e0ab': '105b',
+    '105b:e0c3': '105b',
+    '1199:9079': '1199',
+    '14c3:4d75': '14c3',
+    '1eac:1001': '2c7c',
+    '1eac:1004': '2c7c',
+    '1eac:1007': '2c7c',
+    '2c7c:030a': '2c7c',
+    '2c7c:0313': '2c7c',
+    '2c7c:0314': '2c7c',
+    '2c7c:0801': '2c7c',
+    '413c:81a3': '1199',
+    '413c:81a8': '1199',
+};
+/** `<4 lowercase hex>:<4 lowercase hex>` — the dispatcher's own filename shape. */
+const VID_PID_RE = /^[0-9a-f]{4}:[0-9a-f]{4}$/;
+/**
+ * Fold a vid/pid pair into the dispatcher's key, or `undefined` when it is not a
+ * pair of 4-hex ids. Case is folded because sysfs and udev disagree about it
+ * (`ID_VENDOR_ID` is lowercase, some vendor strings are not) while the dispatcher's
+ * `%04x` is unambiguously lowercase; a `0x` prefix is tolerated for the same reason.
+ * NOTHING ELSE is normalized — a 3-digit or 5-digit id is a different device, not a
+ * sloppy spelling of this one.
+ */
+export function normalizeVidPid(vid, pid) {
+    const fold = (raw) => raw.trim().toLowerCase().replace(/^0x/, '');
+    const key = `${fold(vid)}:${fold(pid)}`;
+    return VID_PID_RE.test(key) ? key : undefined;
+}
+/** True for a string already in the dispatcher's `<vid>:<pid>` shape. */
+export function isFccUnlockKey(value) {
+    return VID_PID_RE.test(value);
+}
+/**
+ * Does ModemManager ship an unlock procedure for this device?
+ *
+ * The three answers are NOT interchangeable, and the third is why this returns a
+ * tri-state rather than a boolean:
+ *   present — a `<vid>:<pid>` entry exists; the toggle can do something.
+ *   absent  — the ids are well-formed and are NOT in the mapping. A positive
+ *             statement about the device, so the module reads `unavailable` and no
+ *             control is offered.
+ *   unknown — we could not read the ids at all. That is a statement about the READ,
+ *             and reporting it as `absent` would hide the module on hardware that
+ *             may well be covered.
+ */
+export function resolveFccUnlockCoverage(vid, pid) {
+    if (vid === undefined || pid === undefined) {
+        return 'unknown';
+    }
+    const key = normalizeVidPid(vid, pid);
+    if (key === undefined) {
+        return 'unknown';
+    }
+    return key in MM_FCC_UNLOCK_COVERAGE ? 'present' : 'absent';
+}
+/** The vendor script a covered key resolves to, for diagnostics and docs. */
+export function fccUnlockVendorScript(key) {
+    return MM_FCC_UNLOCK_COVERAGE[key];
+}
+/** The interpreter a covered key's script invokes (`qmicli` / `mbimcli`). */
+export function fccUnlockRuntimeBinary(key) {
+    const script = fccUnlockVendorScript(key);
+    return script === undefined ? undefined : MM_FCC_UNLOCK_VENDOR_SCRIPTS[script];
+}

package/dist/fcc/index.d.ts

@@ -0,0 +1,3 @@
+export * from './coverage.js';
+export * from './policy-store.js';
+export * from './policy-write.js';

package/dist/fcc/index.js

@@ -0,0 +1,12 @@
+// FCC auto-unlock — the opt-in POLICY surface, and the catalog that gates it.
+//
+// This module implements NO unlock procedure and ships NO unlock script. All it does
+// is record which `<vid>:<pid>` models an operator has opted in for, so that
+// `ceralive-fcc-reconcile` can re-derive ModemManager's own admin-tier symlinks from
+// that record on every boot. The unlocking itself is ModemManager's dispatcher's job,
+// start to finish.
+//
+// Full model, coverage matrix and certification status: `docs/FCC-UNLOCK-COVERAGE.md`.
+export * from './coverage.js';
+export * from './policy-store.js';
+export * from './policy-write.js';

package/dist/fcc/policy-store.d.ts

@@ -0,0 +1,40 @@
+/** The current on-disk schema version. Bump when the persisted shape changes. */
+export declare const FCC_UNLOCK_SCHEMA_VERSION = 1;
+/** The pinned location of the policy of record. `/data` survives a slot swap. */
+export declare const FCC_UNLOCK_POLICY_PATH = "/data/ceralive/fcc-unlock-policy.json";
+/**
+ * The persisted document.
+ *
+ * `unlock` is a TOTAL map from `<vid>:<pid>` to the operator's answer. An absent key
+ * and an explicit `false` are the same fact (not opted in) and both are legal on
+ * disk: a `false` is what an opt-OUT leaves behind, and keeping it is what lets the
+ * shell reconciler prove it parsed a real answer rather than an empty document.
+ */
+export interface PersistedFccUnlockPolicy {
+    readonly schemaVersion: typeof FCC_UNLOCK_SCHEMA_VERSION;
+    readonly savedAtMs: number;
+    readonly unlock: Readonly<Record<string, boolean>>;
+}
+/** A metadata-only log event. Corruption NEVER carries the raw file content. */
+export type FccUnlockLogEvent = {
+    readonly kind: 'corrupt-policy';
+    readonly bytes: number;
+    readonly reason: string;
+};
+export type FccUnlockLogger = (event: FccUnlockLogEvent) => void;
+/** The persistence seam `setFccUnlockPolicy` drives. */
+export interface FccUnlockPolicyStore {
+    /** Load persisted policy; an absent or unreadable file loads as EMPTY. */
+    load(nowMs: number): Promise<PersistedFccUnlockPolicy>;
+    /** Atomically write policy with mode 0600 (temp → chmod → rename). */
+    save(state: PersistedFccUnlockPolicy): Promise<void>;
+}
+export interface FccUnlockPolicyFileStoreOptions {
+    readonly path?: string;
+    readonly logger?: FccUnlockLogger;
+}
+/** The `<vid>:<pid>` models the policy positively enables. Sorted, for stability. */
+export declare function enabledFccUnlockKeys(state: PersistedFccUnlockPolicy): string[];
+/** One model's answer. An unmentioned model is NOT enabled — absence is not consent. */
+export declare function isFccUnlockEnabled(state: PersistedFccUnlockPolicy, key: string): boolean;
+export declare function createFccUnlockPolicyFileStore(options?: FccUnlockPolicyFileStoreOptions): FccUnlockPolicyStore;