@ceralive/modem-control 1.1.0 → 1.2.1

package/README.md

@@ -16,7 +16,7 @@ tree; see [Shape gate](#shape-gate).
 npm install @ceralive/modem-control     # or: bun add @ceralive/modem-control
 ```
 
-ESM only (`"type": "module"`). Node 26 and Bun 1.3 are the runtimes the published
+ESM only (`"type": "module"`). Node 26 and Bun 1.4 are the runtimes the published
 tarball is exercised against on every CI run.
 
 ## Public entry points
@@ -83,10 +83,11 @@ provider runtime. See [`../docs/HUAWEI-HILINK-PROVIDER.md`](../docs/HUAWEI-HILIN
 
 ### ZTE goform provider
 
-`createZteGoformDefinition()` exposes the incompatible `mf79u-legacy` and
-`mf266-salted` authentication profiles without fallback between them. MF79U sends one
-browser-shaped form login with a base64 password; MF266 performs the `LD` challenge,
-salted SHA-256 login, then derives `AD` from version data and `RD`. Session material stays
+`createZteGoformDefinition()` exposes three incompatible authentication profiles without
+fallback between them: MF79U legacy base64 under `LOGIN`, MF79U `LD`-salted SHA-256 under
+the same bare `LOGIN`, and MF266 salted SHA-256 under `LOGIN_MULTI_USER`. One batched
+pre-auth evidence GET selects the exact shape and refuses a reported lockout before any
+credential POST. MF266 derives `AD` from the probed version data and `RD`. Session material stays
 in memory. Unknown ZTE firmware is fingerprinted into a read-only telemetry profile, and
 Wi-Fi writes are absent from every operation surface. See
 [`../docs/MF79U-DIAGNOSIS.md`](../docs/MF79U-DIAGNOSIS.md).
@@ -110,7 +111,10 @@ through `OperationEngine` are refused before execution too.
 `05c6:9024` is evidence of an RNDIS+ADB composition, not a permission. `05c6:9091` is a
 firmware-chosen product id and is **not** proof of DIAG — only an interface descriptor is,
 and production access stays `prohibited` regardless. The supervised, read-only, bench-only
-probe is documented in [`../docs/UFI-DIAG-PROBE.md`](../docs/UFI-DIAG-PROBE.md).
+probe is documented in [`../docs/UFI-DIAG-PROBE.md`](../docs/UFI-DIAG-PROBE.md), together
+with the read-only descriptor capture (`scripts/ufi-himi-capture.sh`) and its bundle
+schema, interface-role classifier and redaction sweep (`scripts/ufi-himi-evidence.ts`).
+Neither ships in the package: `files: ["dist"]`, and bench tooling is not a public surface.
 
 ### NetworkManager adapter — saved vs applied
 
@@ -160,6 +164,26 @@ ModemManager exposes no USB `vid:pid`, so the package cannot build a `BandSku` a
 Both operations expose `describe(context)` alongside their static `descriptor`, because
 a static descriptor cannot carry a device's own catalog or its certification state.
 
+### USB composition — runtime-derived targets, two proof tiers
+
+`operations().usbComposition` asks a known vendor for its current and enumerated USB
+composition modes and offers only targets from that reply after the reply also proves a
+represented return path. Its suppression vocabulary is `unknown-vendor`,
+`no-return-path`, `blocked-by-state`, and `provisioning-disabled`; suppressed states expose
+no targets. Unknown/disabled/blocked decisions happen before transport contact, and a
+capability read sends only the named READ/TEST forms, never a SET.
+
+The current and enumeration replies must both carry a successful AT result before their raw
+bodies are parsed. If either query fails, the operation returns the existing `no-return-path`
+suppression with an empty offer; parseable-looking data followed by `ERROR` cannot make a
+disruptive target writable.
+
+A reviewed catalog transition still provides the strongest success proof: canonical mode
+and USB descriptors must both match. Without one, the weaker fallback proof is the
+re-enumerated device's own post-switch READ reporting the target. AT `OK` is never success.
+The write remains disruptive and requires admission, journal, rollback, and readback hooks.
+Band writes do not share this policy and remain behind their four-proof certification gate.
+
 ### SIM presence is evidence, never inference
 
 `readSimPresence` returns the presence together with the `SimPresenceEvidence` that
@@ -188,6 +212,11 @@ holder PID/start-time metadata, and clean release when the holder process dies.
 is mandatory input; `DEFAULT_MODEM_CONTROL_LOCK_PATH` is only a conventional value callers
 may select. There is no pass-through ownership implementation.
 
+The adapter holds the lock with an external `/bin/cat` whose pipe round-trip acknowledges
+successful acquisition. It never launches `process.execPath -e`: a compiled Bun executable's
+`process.execPath` points back to the application, so re-executing it would parse `-e` as an
+application option and misreport the resulting exit as contention.
+
 One `createModemControlCompositionRoot()` may be live per process. A second construction
 throws, and `actorFor(physicalModemId)` shares one actor for that modem across all callers in
 the root. `UhubctlPort` has no control-package implementation; an embedding process must

package/dist/backend/at-lease.d.ts

@@ -1,5 +1,7 @@
 import { type EpochMillis } from '../domain/index.js';
-/** The baseline allowlist — identify only. Catalog commands are unioned in per SKU. */
+/** Named read-only fence: the exact vendor READ/TEST forms reviewed for runtime discovery. */
+export declare const AT_RUNTIME_QUERY_ALLOWLIST: ReadonlySet<string>;
+/** Identify plus reviewed runtime queries. Exact catalog/runtime SET commands union in per use. */
 export declare const AT_BASELINE_ALLOWLIST: ReadonlySet<string>;
 /** Union the baseline allowlist with a catalog entry's declared transition commands. */
 export declare function computeAtAllowlist(commands: Iterable<string>): ReadonlySet<string>;

package/dist/backend/at-lease.js

@@ -12,8 +12,17 @@
 //      stripped before it is stored.
 import { epochMillis } from '../domain/index.js';
 import { redact } from '../redact.js';
-/** The baseline allowlist — identify only. Catalog commands are unioned in per SKU. */
-export const AT_BASELINE_ALLOWLIST = new Set(['ATI']);
+import { RUNTIME_COMPOSITION_QUERY_REGISTRY } from '../usb-mode/runtime-capability.js';
+/** Named read-only fence: the exact vendor READ/TEST forms reviewed for runtime discovery. */
+export const AT_RUNTIME_QUERY_ALLOWLIST = new Set(Object.values(RUNTIME_COMPOSITION_QUERY_REGISTRY).flatMap(({ current, enumerate }) => [
+    current,
+    enumerate,
+]));
+/** Identify plus reviewed runtime queries. Exact catalog/runtime SET commands union in per use. */
+export const AT_BASELINE_ALLOWLIST = new Set([
+    'ATI',
+    ...AT_RUNTIME_QUERY_ALLOWLIST,
+]);
 /** Union the baseline allowlist with a catalog entry's declared transition commands. */
 export function computeAtAllowlist(commands) {
     return new Set([...AT_BASELINE_ALLOWLIST, ...commands]);

package/dist/backend/recovery-ladder.d.ts

@@ -5,7 +5,7 @@ import type { ModemActor } from './modem-actor.js';
 import { type PowerHook } from './power-contract.js';
 import type { FaultAttribution } from './recovery-attribution.js';
 import { type RecoveryBudget, type RecoveryBudgetState } from './recovery-budget.js';
-export declare const LADDER_ORDER: readonly ["nmCycle", "mmCycle", "reset", "powerCycle"];
+export declare const LADDER_ORDER: readonly ['nmCycle', 'mmCycle', 'reset', 'powerCycle'];
 export type RecoveryRung = (typeof LADDER_ORDER)[number];
 /** Context handed to each disruptive rung. */
 export interface RecoveryStepContext {

package/dist/backend/transition-preconditions.d.ts

@@ -1,6 +1,6 @@
 import type { EpochMillis, IdentityConfidence } from '../domain/index.js';
 import type { ConnectionId, DeviceIfname } from '../ports/index.js';
-import { type CatalogEntry, type CertifiedCatalog, type MmUsbMode, type PermittedTransition, type SkuDiscriminator } from '../usb-mode/index.js';
+import { type CatalogEntry, type CertifiedCatalog, type MmUsbMode, type PermittedTransition, type RuntimeCompositionCapability, type RuntimeCompositionMode, type RuntimeCompositionVendor, type SkuDiscriminator } from '../usb-mode/index.js';
 import type { InterlockTarget, LifecycleInterlock } from './lifecycle-interlock.js';
 /** A held "transition active" interlock — released when the transaction ends. */
 export interface InterlockHold {
@@ -21,12 +21,8 @@ export interface TransitionReadiness {
     /** The identity confidence from A3.2's ladder; `'low'` refuses the transition. */
     readonly identityConfidence: IdentityConfidence;
 }
-/** One USB-mode transition request. */
-export interface UsbModeTransitionRequest {
+type UsbModeTransitionRequestBase = {
     readonly stableKey: string;
-    readonly sku: SkuDiscriminator;
-    readonly fromMode: MmUsbMode;
-    readonly toMode: MmUsbMode;
     readonly connectionId: ConnectionId;
     readonly deviceIfname: DeviceIfname;
     /** Physical-topology UID captured BEFORE the switch — survives re-enumeration. */
@@ -40,7 +36,22 @@ export interface UsbModeTransitionRequest {
     readonly now: EpochMillis;
     /** Live readiness, re-polled at entry AND in-actor (TOCTOU-safe). */
     probeReadiness(): Promise<TransitionReadiness>;
-}
+};
+export type CatalogUsbModeTransitionRequest = UsbModeTransitionRequestBase & {
+    readonly strategy?: 'catalog';
+    readonly sku: SkuDiscriminator;
+    readonly fromMode: MmUsbMode;
+    readonly toMode: MmUsbMode;
+};
+export type RuntimeUsbModeTransitionRequest = UsbModeTransitionRequestBase & {
+    readonly strategy: 'runtime';
+    readonly vendor: RuntimeCompositionVendor;
+    readonly sku?: SkuDiscriminator;
+    readonly fromMode: RuntimeCompositionMode;
+    readonly toMode: RuntimeCompositionMode;
+    readonly capability: RuntimeCompositionCapability;
+};
+export type UsbModeTransitionRequest = CatalogUsbModeTransitionRequest | RuntimeUsbModeTransitionRequest;
 /** How a transition ended. */
 export type UsbModeTransitionOutcome = {
     readonly status: 'refused';
@@ -57,11 +68,24 @@ export type UsbModeTransitionOutcome = {
     readonly reason: string;
     readonly steps: readonly string[];
 };
-/** The result of a precondition check — the matched entry/transition, or a reason. */
+export type UsbModeTransitionPlan = {
+    readonly atCommand: string;
+    readonly applyCommand?: string;
+    readonly proof: {
+        readonly tier: 'catalog-descriptors';
+        readonly transition: PermittedTransition;
+    } | {
+        readonly tier: 'runtime-requery';
+        readonly vendor: RuntimeCompositionVendor;
+        readonly target: RuntimeCompositionMode;
+        readonly currentQuery: string;
+    };
+};
 export type PreconditionResult = {
     readonly ok: true;
-    readonly entry: CatalogEntry;
-    readonly transition: PermittedTransition;
+    readonly entry?: CatalogEntry;
+    readonly plan: UsbModeTransitionPlan;
+    readonly allowlistedCommands: readonly string[];
 } | {
     readonly ok: false;
     readonly reason: string;
@@ -74,3 +98,4 @@ export type PreconditionResult = {
  * (identity, interlock), so a refusal touches as little as possible.
  */
 export declare function checkTransitionPreconditions(request: UsbModeTransitionRequest, catalog: CertifiedCatalog, interlock: TransitionInterlock): Promise<PreconditionResult>;
+export {};

package/dist/backend/transition-preconditions.js

@@ -12,7 +12,7 @@
 // transition→streaming gate (mark "transition active" until released). The Phase-A
 // stub allows both; Phase B wires CeraUI's streaming-admission check into the same
 // interface without changing the transaction.
-import { findCatalogEntry, findPermittedTransition, } from '../usb-mode/index.js';
+import { buildRuntimeCompositionSetCommand, findCatalogEntry, findPermittedTransition, RUNTIME_COMPOSITION_QUERY_REGISTRY, } from '../usb-mode/index.js';
 const NO_OP_HOLD = {
     release() {
         return Promise.resolve();
@@ -27,6 +27,54 @@ export const ALLOW_ALL_TRANSITION_INTERLOCK = {
         return Promise.resolve(NO_OP_HOLD);
     },
 };
+function sameRuntimeMode(left, right) {
+    return Object.is(left, right);
+}
+function runtimePlan(request, catalog) {
+    const capability = request.capability;
+    if (capability.status !== 'available')
+        return { ok: false, reason: 'runtime capability unknown' };
+    if (!sameRuntimeMode(capability.current, request.fromMode))
+        return { ok: false, reason: 'runtime current mode changed' };
+    if (!capability.returnPathProven ||
+        !capability.offerable.some((mode) => sameRuntimeMode(mode, request.toMode)))
+        return { ok: false, reason: 'no-return-path' };
+    const atCommand = buildRuntimeCompositionSetCommand(request.vendor, request.toMode);
+    if (atCommand === undefined)
+        return { ok: false, reason: 'runtime target command unavailable' };
+    const entry = request.sku === undefined ? undefined : findCatalogEntry(catalog, request.sku);
+    if (entry !== undefined) {
+        const reviewed = entry.permittedTransitions.find((transition) => transition.atCommand === atCommand);
+        if (reviewed !== undefined) {
+            return {
+                ok: true,
+                entry,
+                plan: {
+                    atCommand: reviewed.atCommand,
+                    ...(reviewed.applyCommand === undefined ? {} : { applyCommand: reviewed.applyCommand }),
+                    proof: { tier: 'catalog-descriptors', transition: reviewed },
+                },
+                allowlistedCommands: entry.permittedTransitions.flatMap((transition) => transition.applyCommand === undefined
+                    ? [transition.atCommand]
+                    : [transition.atCommand, transition.applyCommand]),
+            };
+        }
+    }
+    return {
+        ok: true,
+        ...(entry === undefined ? {} : { entry }),
+        plan: {
+            atCommand,
+            proof: {
+                tier: 'runtime-requery',
+                vendor: request.vendor,
+                target: request.toMode,
+                currentQuery: RUNTIME_COMPOSITION_QUERY_REGISTRY[request.vendor].current,
+            },
+        },
+        allowlistedCommands: [atCommand],
+    };
+}
 /**
  * Check every transition precondition against the LIVE inputs. Called at entry and
  * again in-actor; a request that passed at entry can fail here if the identity
@@ -41,17 +89,37 @@ export async function checkTransitionPreconditions(request, catalog, interlock)
     if (!request.maintenance) {
         return { ok: false, reason: 'maintenance flag is required' };
     }
-    const entry = findCatalogEntry(catalog, request.sku);
-    if (entry === undefined) {
-        return { ok: false, reason: `uncertified SKU ${request.sku.vidPid} ${request.sku.model}` };
+    let staticResult;
+    if (request.strategy === 'runtime') {
+        staticResult = runtimePlan(request, catalog);
     }
-    const transition = findPermittedTransition(entry, request.fromMode, request.toMode);
-    if (transition === undefined) {
-        return {
-            ok: false,
-            reason: `transition ${request.fromMode}->${request.toMode} not permitted for ${request.sku.model}`,
+    else {
+        const entry = findCatalogEntry(catalog, request.sku);
+        if (entry === undefined) {
+            return { ok: false, reason: `uncertified SKU ${request.sku.vidPid} ${request.sku.model}` };
+        }
+        const transition = findPermittedTransition(entry, request.fromMode, request.toMode);
+        if (transition === undefined) {
+            return {
+                ok: false,
+                reason: `transition ${request.fromMode}->${request.toMode} not permitted for ${request.sku.model}`,
+            };
+        }
+        staticResult = {
+            ok: true,
+            entry,
+            plan: {
+                atCommand: transition.atCommand,
+                ...(transition.applyCommand === undefined ? {} : { applyCommand: transition.applyCommand }),
+                proof: { tier: 'catalog-descriptors', transition },
+            },
+            allowlistedCommands: entry.permittedTransitions.flatMap((candidate) => candidate.applyCommand === undefined
+                ? [candidate.atCommand]
+                : [candidate.atCommand, candidate.applyCommand]),
         };
     }
+    if (!staticResult.ok)
+        return staticResult;
     const readiness = await request.probeReadiness();
     if (readiness.identityConfidence === 'low') {
         return { ok: false, reason: 'low-confidence identity — refusing to transition' };
@@ -60,5 +128,5 @@ export async function checkTransitionPreconditions(request, catalog, interlock)
     if (!verdict.allow) {
         return { ok: false, reason: `interlock held: ${verdict.reason}` };
     }
-    return { ok: true, entry, transition };
+    return staticResult;
 }

package/dist/backend/usb-mode-transition.js

@@ -11,13 +11,16 @@
 //   8 resolve new ifname → 9 reactivate (uuid, newIfname) → 10 release interlock
 //   (finally, always).
 //
-// THE POSTCONDITION IS THE ONLY PROOF OF SUCCESS. An AT `OK` proves nothing — only a
-// re-enumerated device whose descriptors AND observed mode equal the catalog target
-// counts. On a postcondition MISMATCH the whole transaction fails `degraded`, does NOT
+// THE POSTCONDITION IS THE ONLY PROOF OF SUCCESS. An AT `OK` proves nothing. Tier 1 is
+// the strongest proof and remains unchanged: a reviewed catalog transition must match
+// both descriptors and canonical mode. Tier 2 exists only when no reviewed transition
+// matches: the re-enumerated device must report the raw target through its own vendor READ.
+// Tier 2 is explicitly weaker because it proves reported mode, not descriptor composition.
+// On a postcondition MISMATCH the whole transaction fails `degraded`, does NOT
 // reactivate, and still releases the interlock via `finally`. A hung command trips the
 // AT watchdog, which force-uninhibits so the system reprobes rather than wedging.
 import { deviceIfname } from '../ports/index.js';
-import { CERTIFIED_CATALOG } from '../usb-mode/index.js';
+import { CERTIFIED_CATALOG, readRuntimeCompositionCurrent, } from '../usb-mode/index.js';
 import { AtCommandLease, computeAtAllowlist, } from './at-lease.js';
 import { descriptorsMatch, detectUsbMode } from './device-classifier.js';
 import { ALLOW_ALL_TRANSITION_INTERLOCK, checkTransitionPreconditions, } from './transition-preconditions.js';
@@ -77,14 +80,14 @@ export class UsbModeTransition {
         }
         const hold = await this.#interlock.hold({ stableKey: request.stableKey });
         try {
-            return await this.#runTransaction(request, recheck.entry.permittedTransitions, recheck.transition, steps);
+            return await this.#runTransaction(request, recheck.allowlistedCommands, recheck.plan, steps);
         }
         finally {
             steps.push('release-interlock');
             await hold.release().catch(() => undefined);
         }
     }
-    async #runTransaction(request, allCommands, transition, steps) {
+    async #runTransaction(request, allowlistedCommands, plan, steps) {
         let inhibit;
         let reactivated = false;
         const forceUninhibit = async () => {
@@ -98,7 +101,7 @@ export class UsbModeTransition {
         };
         const lease = new AtCommandLease({
             sender: this.#atSender,
-            allowlist: computeAtAllowlist(allCommands.flatMap((t) => t.applyCommand === undefined ? [t.atCommand] : [t.atCommand, t.applyCommand])),
+            allowlist: computeAtAllowlist(allowlistedCommands),
             timeoutMs: this.#watchdogMs,
             onWatchdog: forceUninhibit,
             ...(this.#audit !== undefined ? { audit: this.#audit } : {}),
@@ -110,10 +113,10 @@ export class UsbModeTransition {
             inhibit = await this.#modemManager.inhibit(request.inhibitUid);
             // AT `OK` is IGNORED for success — only the postcondition below decides.
             steps.push('at-command');
-            await lease.run(transition.atCommand, { inhibitUid: request.inhibitUid });
-            if (transition.applyCommand !== undefined) {
+            await lease.run(plan.atCommand, { inhibitUid: request.inhibitUid });
+            if (plan.applyCommand !== undefined) {
                 steps.push('apply-command');
-                await lease.run(transition.applyCommand, { inhibitUid: request.inhibitUid });
+                await lease.run(plan.applyCommand, { inhibitUid: request.inhibitUid });
             }
             steps.push('await-port-drop');
             await this.#awaitPortDrop(request.cachedPhysicalUid);
@@ -126,15 +129,32 @@ export class UsbModeTransition {
             steps.push('await-reenumeration');
             const device = await this.#awaitReenumeration(request.cachedPhysicalUid);
             steps.push('postcondition');
-            const observedMode = detectUsbMode(device);
-            const descriptorsOk = descriptorsMatch(device, transition.expectedDescriptors);
-            if (observedMode !== request.toMode || !descriptorsOk) {
-                return {
-                    status: 'failed',
-                    degraded: true,
-                    reason: `postcondition mismatch: observed ${observedMode ?? 'unknown'} vs target ${request.toMode}; descriptors ${descriptorsOk ? 'ok' : 'mismatch'}`,
-                    steps,
-                };
+            if (plan.proof.tier === 'catalog-descriptors') {
+                const observedMode = detectUsbMode(device);
+                const descriptorsOk = descriptorsMatch(device, plan.proof.transition.expectedDescriptors);
+                if (observedMode !== plan.proof.transition.to || !descriptorsOk) {
+                    return {
+                        status: 'failed',
+                        degraded: true,
+                        reason: `postcondition mismatch: observed ${observedMode ?? 'unknown'} vs target ${plan.proof.transition.to}; descriptors ${descriptorsOk ? 'ok' : 'mismatch'}`,
+                        steps,
+                    };
+                }
+            }
+            else {
+                steps.push('postcondition-runtime-read');
+                const response = await lease.run(plan.proof.currentQuery, {
+                    inhibitUid: request.inhibitUid,
+                });
+                const observed = readRuntimeCompositionCurrent(plan.proof.vendor, response.raw);
+                if (!Object.is(observed, plan.proof.target)) {
+                    return {
+                        status: 'failed',
+                        degraded: true,
+                        reason: `runtime readback mismatch: observed ${observed ?? 'unknown'} vs target ${plan.proof.target}`,
+                        steps,
+                    };
+                }
             }
             steps.push('resolve-ifname');
             const newIfname = this.#resolveIfname(device);

package/dist/capability/five-g-preference.d.ts

@@ -13,7 +13,7 @@ import type { CapabilityEvidence } from './support-claim.js';
  *               selector structurally cannot express.
  *   5g-off    — allow everything the modem supports EXCEPT 5G.
  */
-export declare const FIVE_G_PREFERENCES: readonly ["5g-only", "prefer-5g", "prefer-4g", "5g-off"];
+export declare const FIVE_G_PREFERENCES: readonly ['5g-only', 'prefer-5g', 'prefer-4g', '5g-off'];
 export type FiveGPreference = (typeof FIVE_G_PREFERENCES)[number];
 /** One `(allowed, preferred)` pair, the shape MM's `CurrentModes` really carries. */
 export interface RadioModeSet {
@@ -44,7 +44,7 @@ export interface FiveGRadioTarget {
  * reads as "nobody asked"; a stated `not-exposed-by-modemmanager` tells an
  * operator looking for an SA toggle why there is none.
  */
-export declare const NR_MODE_UNSUPPORTED_REASON: "not-exposed-by-modemmanager";
+export declare const NR_MODE_UNSUPPORTED_REASON: 'not-exposed-by-modemmanager';
 export interface NrModeSelection {
     readonly supported: false;
     readonly reason: typeof NR_MODE_UNSUPPORTED_REASON;

package/dist/capability/support-claim.d.ts

@@ -1,5 +1,5 @@
 /** The seven gated capability modules. */
-export declare const CAPABILITY_MODULES: readonly ["band-lock", "sms", "five-g-pref", "fcc-auto-unlock", "gps", "ussd", "esim"];
+export declare const CAPABILITY_MODULES: readonly ['band-lock', 'sms', 'five-g-pref', 'fcc-auto-unlock', 'gps', 'ussd', 'esim'];
 export type CapabilityModule = (typeof CAPABILITY_MODULES)[number];
 /**
  * The ladder, lowest rung first. `resolveSupportClaim` answers with the highest
@@ -12,7 +12,7 @@ export type CapabilityModule = (typeof CAPABILITY_MODULES)[number];
  *   certified   — capable AND proven on this exact model+firmware. The ONLY rung
  *                 a support matrix or a doc may claim.
  */
-export declare const SUPPORT_CLAIM_STATES: readonly ["unavailable", "implemented", "enabled", "capable", "certified"];
+export declare const SUPPORT_CLAIM_STATES: readonly ['unavailable', 'implemented', 'enabled', 'capable', 'certified'];
 export type SupportClaimState = (typeof SUPPORT_CLAIM_STATES)[number];
 /** What a probe found. `unknown` is an answer about the READ, not the device. */
 export type CapabilityEvidence = 'present' | 'absent' | 'unknown';

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

@@ -9,7 +9,7 @@ export interface ShadowModemState {
     readonly simPresent?: boolean;
     readonly networkType?: ShadowGeneration;
 }
-export declare const SHADOW_COMPARABLE_FIELDS: readonly ["present", "registration", "signalBucket", "operatorName", "simPresent", "networkType"];
+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;

package/dist/fcc/coverage.d.ts

@@ -1,35 +1,35 @@
 /** 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";
+    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";
+    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";
+    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;
 /**

package/dist/hardware/router-parsers.d.ts

@@ -8,7 +8,7 @@ export type SimPresenceFacts = {
 /** The mmcli spelling of `MM_MODEM_STATE_FAILED_REASON_SIM_MISSING` — the ONLY proof of absence. */
 export declare const SIM_MISSING_FAILED_REASON = "sim-missing";
 /** The fields a presence decision may be drawn from, in the order they are inspected. */
-export declare const SIM_PRESENCE_FIELDS: readonly ["sim", "simSlots", "failedReason"];
+export declare const SIM_PRESENCE_FIELDS: readonly ['sim', 'simSlots', 'failedReason'];
 export type SimPresenceField = (typeof SIM_PRESENCE_FIELDS)[number];
 /**
  * WHICH FACT decided a SIM presence — the whole point of this type.

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from './hardware/router-parsers.js';
 export * from './journal/index.js';
 export * from './location/index.js';
 export * from './observations/index.js';
+export * from './operation-ids.js';
 export * from './operations/index.js';
 export * from './ports/index.js';
 export * from './providers/index.js';

package/dist/index.js

@@ -15,6 +15,7 @@ export * from './hardware/router-parsers.js';
 export * from './journal/index.js';
 export * from './location/index.js';
 export * from './observations/index.js';
+export * from './operation-ids.js';
 export * from './operations/index.js';
 export * from './ports/index.js';
 export * from './providers/index.js';

package/dist/journal/legacy-ceraui.d.ts

@@ -5,9 +5,9 @@ import { type JournalOperationRecord, type JournalRecovery } from './recovery.js
 export declare const LEGACY_CERAUI_JOURNAL_VERSION = 1;
 /** CeraUI's cap on retained history entries per slot. */
 export declare const LEGACY_CERAUI_HISTORY_CAP = 32;
-export declare const LEGACY_CERAUI_MUTATION_STATES: readonly ["armed", "executing", "completed", "failed", "acknowledged", "device-absent-quarantine", "decommissioned", "recommission-pending"];
+export declare const LEGACY_CERAUI_MUTATION_STATES: readonly ['armed', 'executing', 'completed', 'failed', 'acknowledged', 'device-absent-quarantine', 'decommissioned', 'recommission-pending'];
 export type LegacyCeraUiMutationState = (typeof LEGACY_CERAUI_MUTATION_STATES)[number];
-export declare const LEGACY_CERAUI_ACK_MODES: readonly ["verified-rollback", "force-rebaseline"];
+export declare const LEGACY_CERAUI_ACK_MODES: readonly ['verified-rollback', 'force-rebaseline'];
 export type LegacyCeraUiAckMode = (typeof LEGACY_CERAUI_ACK_MODES)[number];
 export interface LegacyCeraUiHistoryEntry {
     readonly state: LegacyCeraUiMutationState;

package/dist/observations/metric.d.ts

@@ -1,6 +1,20 @@
 import type { RouterSignalMetric, RouterSignalUnknownReason } from '../hardware/router-parsers.js';
 import type { MetricProvenance } from './provenance.js';
-export declare const METRIC_UNKNOWN_REASONS: readonly ["unsupported", "not-reported", "not-observed", "malformed", "auth-expired", "refused", "unreachable"];
+export declare const METRIC_UNKNOWN_REASONS: readonly [
+/** A positive claim about the SOURCE: it cannot express this datum at all. */
+'unsupported', 
+/** The source answered and simply did not include this field. */
+'not-reported', 
+/** Nobody has read this yet. Says nothing about the source or the device. */
+'not-observed', 
+/** The source answered with something this layer could not decode. */
+'malformed', 
+/** The source refused the read; the session needs re-authentication. */
+'auth-expired', 
+/** The source answered with an explicit refusal code for this field. */
+'refused', 
+/** The source could not be reached for this read. */
+'unreachable'];
 export type MetricUnknownReason = (typeof METRIC_UNKNOWN_REASONS)[number];
 /**
  * The two classes an unknown reason falls into.

package/dist/observations/provenance.d.ts

@@ -11,7 +11,7 @@ import type { EpochMillis, ObservationAuthority, SourceEpoch } from '../domain/i
  * reading. Giving it its own kind is what keeps a bearer observation attributable to
  * NM rather than laundered through whichever provider happened to read the modem.
  */
-export declare const OBSERVATION_SOURCE_KINDS: readonly ["modemmanager", "huawei-hilink", "zte-goform", "ufi-himiapi", "networkmanager"];
+export declare const OBSERVATION_SOURCE_KINDS: readonly ['modemmanager', 'huawei-hilink', 'zte-goform', 'ufi-himiapi', 'networkmanager'];
 export type ObservationSourceKind = (typeof OBSERVATION_SOURCE_KINDS)[number];
 /**
  * A provider-native value, kept exactly as the provider expressed it.
@@ -45,7 +45,7 @@ export type MetricProvenance = {
  * and never carries its value: a body can hold an ICCID or a one-time code, and a
  * diagnostic is the one place a reviewer reads verbatim.
  */
-export declare const OBSERVATION_DIAGNOSTIC_CODES: readonly ["unparseable-body", "empty-body", "auth-expired", "field-shape-unrecognized"];
+export declare const OBSERVATION_DIAGNOSTIC_CODES: readonly ['unparseable-body', 'empty-body', 'auth-expired', 'field-shape-unrecognized'];
 export type ObservationDiagnosticCode = (typeof OBSERVATION_DIAGNOSTIC_CODES)[number];
 export type ObservationDiagnosticNote = {
     readonly code: ObservationDiagnosticCode;

package/dist/observations/reading.d.ts

@@ -34,7 +34,7 @@ export type ObservationReading<T> = (ReadingBase & {
     readonly reason: MetricUnknownReason;
     readonly provenance: MetricProvenance;
 });
-export declare const OBSERVATION_READING_STATES: readonly ["fresh", "stale", "unavailable", "unknown"];
+export declare const OBSERVATION_READING_STATES: readonly ['fresh', 'stale', 'unavailable', 'unknown'];
 export type ObservationReadingState = (typeof OBSERVATION_READING_STATES)[number];
 /**
  * Project one metric out of an envelope.

package/dist/observations/state-separation.d.ts

@@ -38,7 +38,7 @@ export type ModemStateView<TDesired, TApplied, TObserved> = {
     readonly applied: AppliedConfiguration<TApplied> | null;
     readonly observed: ObservedState<TObserved>;
 };
-export declare const STATE_VIEW_SLOTS: readonly ["desired", "applied", "observed"];
+export declare const STATE_VIEW_SLOTS: readonly ['desired', 'applied', 'observed'];
 export type StateViewSlot = (typeof STATE_VIEW_SLOTS)[number];
 export type SlotComparison = {
     readonly status: 'aligned';