@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/radio/band-truth.js

@@ -0,0 +1,92 @@
+// The band-write descriptor — the certification gate, expressed as an operation contract.
+//
+// It ADDS NOTHING to `band/certification.ts`. That module already owns the four-proof
+// per-SKU catalog, the fail-closed lookup, and the `offerableBands` narrowing, and it
+// is the only place a SKU may be declared certified. What was missing was the other
+// end of the wire: a band write's OPERATION DESCRIPTOR did not say that it is
+// disruptive-with-a-certification-requirement, so the gate lived only inside the
+// provider's capability flag and a consumer reading the descriptor could not see it.
+//
+// TWO INDEPENDENT FENCES, deliberately. `availability: refused` is what a consumer
+// reads to decide whether to offer the control at all; the provider's own
+// `bandWrite` capability check is what refuses the call if one is made anyway. A gate
+// that exists only in the descriptor is advisory, and a gate that exists only in the
+// provider is invisible — a band lock can take a working uplink off the air, so it
+// gets both.
+import { offerableBands } from '../band/index.js';
+import { defineOperationDescriptor } from '../domain/index.js';
+export const BAND_WRITE_OPERATION_ID = 'modemmanager.bands';
+/** The refusal reasons a band write may carry. Certification is the first gate. */
+export const BAND_WRITE_REFUSAL = 'band-certification-required';
+export const BAND_READ_REFUSAL = 'band-read-unsupported';
+export const BAND_NONE_OFFERABLE_REFUSAL = 'no-offerable-certified-bands';
+export function describeBandWriteCertification(input) {
+    const offerable = offerableBands(input.entry, input.supported);
+    return input.entry === undefined
+        ? { required: true, satisfied: false, reason: BAND_WRITE_REFUSAL, offerable }
+        : { required: true, satisfied: true, reason: 'band-certification-proven', offerable };
+}
+function sameBandSet(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const sorted = [...right].sort();
+    return [...left].sort().every((band, index) => band === sorted[index]);
+}
+/**
+ * Whether a band readback confirms the write.
+ *
+ * A NARROWING lock must match exactly — a superset is a different lock from the one
+ * that was asked for. The reset (`['any']`) is the exception ModemManager forces:
+ * releasing a lock is `SetCurrentBands([ANY])`, and a modem afterwards reports either
+ * `any` or its whole supported set, both of which mean "no lock is in force".
+ */
+export function bandWriteReadbackMatches(requested, observed) {
+    if (requested.length === 1 && requested[0] === 'any') {
+        return ((observed.current.length === 1 && observed.current[0] === 'any') ||
+            sameBandSet(observed.current, observed.supported));
+    }
+    return sameBandSet(requested, observed.current);
+}
+/**
+ * The live band-write descriptor.
+ *
+ * `mutationImpact: 'disruptive'` because `SetCurrentBands` re-registers the radio and
+ * drops the bearer underneath NetworkManager; `readback` is REQUIRED because an
+ * accepted-but-ignored band write is the failure mode the catalog's own `readback`
+ * proof exists to catch, and it looks like success from the call site alone.
+ */
+export function buildBandWriteDescriptor(input) {
+    const refusal = !input.certification.satisfied
+        ? BAND_WRITE_REFUSAL
+        : input.certification.offerable.length === 0
+            ? BAND_NONE_OFFERABLE_REFUSAL
+            : undefined;
+    return defineOperationDescriptor({
+        id: BAND_WRITE_OPERATION_ID,
+        support: {
+            read: input.readSupported
+                ? { supported: true }
+                : { supported: false, reason: BAND_READ_REFUSAL },
+            write: input.certification.satisfied
+                ? { supported: true }
+                : { supported: false, reason: BAND_WRITE_REFUSAL },
+        },
+        authority: 'provider',
+        provider: input.provider,
+        constraints: { kind: 'allowed-values', values: [input.certification.offerable] },
+        livePreconditions: ['modem-present', 'runtime-interface-present', 'band-certification-present'],
+        availability: refusal === undefined ? { state: 'available' } : { state: 'refused', reason: refusal },
+        mutationImpact: 'disruptive',
+        retryClass: 'never',
+        readback: {
+            required: true,
+            reason: 'band-write-readback',
+            matches: bandWriteReadbackMatches,
+        },
+        rollback: { required: false },
+        journal: { required: true, reason: 'disruptive-radio-write' },
+        admission: { required: true, reason: 'provider-mutation' },
+        evidence: { profiles: [input.profile], firmware: [] },
+        confidence: 'high',
+    });
+}

package/dist/radio/index.d.ts

@@ -0,0 +1,3 @@
+export * from './band-truth.js';
+export * from './mode-combinations.js';
+export * from './mode-truth.js';

package/dist/radio/index.js

@@ -0,0 +1,10 @@
+// Radio capability TRUTH: the modem's own mode catalog and band-write gate, verbatim.
+//
+// It sits beside `src/band/` (the band vocabulary and per-SKU certification catalog)
+// rather than inside it, because a mode combination is not a band and the two have
+// different safety models — a mode change is disruptive-but-reversible, a band lock
+// can strand a radio where nothing registers. Reachable through the package ROOT
+// entry, deliberately NOT a new package subpath (the todo 17/18/23 precedent).
+export * from './band-truth.js';
+export * from './mode-combinations.js';
+export * from './mode-truth.js';

package/dist/radio/mode-combinations.d.ts

@@ -0,0 +1,78 @@
+/** A mode as every operator-facing surface spells it. Opaque; compare by equality. */
+export type ModeName = string;
+/**
+ * `MM_MODEM_MODE_NONE` (0) — the modem expresses no preference within its allowed set.
+ * A legal, load-bearing value; never a stand-in for "not reported".
+ */
+export declare const MODE_NONE = "none";
+/** `MM_MODEM_MODE_ANY` (0xFFFFFFFF) — every mode the modem has. */
+export declare const MODE_ANY = "any";
+/** Decode one `MMModemMode` bit. Total: an unnamed bit round-trips. */
+export declare function modeName(bit: number): ModeName;
+/** Encode one mode name. `undefined` for a name this build cannot place. */
+export declare function modeValue(name: ModeName): number | undefined;
+/** True when this build recognises the name (a `mode-bit-<n>` passthrough does not). */
+export declare function isNamedMode(name: ModeName): boolean;
+/**
+ * Split a mask into its set bits, named where this build can and passed through where
+ * it cannot. A zero mask is the EMPTY set — the caller decides whether that reads as
+ * `none` (a preference) or as an anomaly (an allowed set nothing can be chosen from).
+ */
+export declare function modeNames(mask: number): readonly ModeName[];
+/** Encode a set of mode names into one mask. Fails closed on an unplaceable name. */
+export declare function encodeModeNames(names: readonly ModeName[]): {
+    readonly ok: true;
+    readonly mask: number;
+} | {
+    readonly ok: false;
+    readonly unknown: ModeName;
+};
+/** Why a combination could not be fully placed. Never a reason to hide it. */
+export declare const MODE_COMBINATION_ANOMALIES: readonly ["unnamed-allowed-bit", "unnamed-preferred-bit", "preferred-not-in-allowed", "preferred-not-singular", "empty-allowed"];
+export type ModeCombinationAnomaly = (typeof MODE_COMBINATION_ANOMALIES)[number];
+export type ModeCombinationClassification = 'named' | 'unknown-combination';
+/**
+ * One `(allowed, preferred)` pair, decoded without loss.
+ *
+ * The masks are retained ALONGSIDE the names so a consumer can always reproduce the
+ * exact bytes the modem reported, whatever this build managed to name.
+ */
+export type ModeCombination = {
+    readonly allowedMask: number;
+    readonly allowed: readonly ModeName[];
+    readonly preferredMask: number;
+    /** `none` when the modem stated no preference — verbatim, never a substitute. */
+    readonly preferred: ModeName;
+    readonly classification: ModeCombinationClassification;
+    readonly anomalies: readonly ModeCombinationAnomaly[];
+};
+/**
+ * A `SupportedModes` catalog: everything decoded, plus everything that could not be.
+ *
+ * `undecodable` exists so the no-drop property is structural rather than a promise —
+ * `combinations.length + undecodable.length` is the member count the provider sent.
+ */
+export type ModeCombinationSet = {
+    readonly combinations: readonly ModeCombination[];
+    /** Members that were not a `(uu)` pair, retained exactly as the provider sent them. */
+    readonly undecodable: readonly unknown[];
+};
+/** Build a combination from two raw masks, recording every anomaly it carries. */
+export declare function modeCombination(allowedMask: number, preferredMask: number): ModeCombination;
+/** True when the modem stated no preference within this combination's allowed set. */
+export declare function statesNoPreference(combination: ModeCombination): boolean;
+/** Decode one `CurrentModes` `(uu)`. `undefined` only when the value is not a pair. */
+export declare function decodeModeCombination(value: unknown): ModeCombination | undefined;
+/**
+ * Decode a `SupportedModes` `a(uu)`.
+ *
+ * Nothing is dropped: a member that is not a pair lands in `undecodable`, and a pair
+ * this build cannot fully name lands in `combinations` classified
+ * `unknown-combination`. A non-array value is an empty catalog, not an error — a modem
+ * that advertises no mode control is a real reading.
+ */
+export declare function decodeSupportedModeCombinations(value: unknown): ModeCombinationSet;
+/** True when any advertised combination carries an anomaly this build could not place. */
+export declare function hasUnknownCombination(set: ModeCombinationSet): boolean;
+/** Whether a mask names a mode this build recognises across every set bit. */
+export declare function isFullyNamedMask(mask: number): boolean;

package/dist/radio/mode-combinations.js

@@ -0,0 +1,198 @@
+// `MMModemMode` ↔ mode NAME, and the (allowed, preferred) COMBINATION, verbatim.
+//
+// ModemManager advertises what a radio can do as `Modem.SupportedModes`, an `a(uu)`
+// of (allowed-mask, preferred-mask) pairs, and what it is doing as `Modem.CurrentModes`,
+// one `(uu)`. Everything an operator may legally ask for is in that list, and this
+// module's whole job is to carry it across UNCHANGED.
+//
+// THREE THINGS ARE ROUTINELY LOST BY A DECODER THAT MEANS WELL, and each one is a
+// documented CeraLive case rather than a hypothetical:
+//
+//   1. `preferred: 0` (`MM_MODEM_MODE_NONE`). The bench Fibocom FM350-GL advertises
+//      exactly one combination, and its preferred mask is 0 — the modem allows a set
+//      of modes and states NO preference within it. That is a real, legal answer, and
+//      it is NOT the same as "prefer the highest allowed mode". Substituting a default
+//      shows an operator a preference the modem never expressed and cannot be returned
+//      to. `preferred` is therefore the name `none`, carried through to the operation
+//      descriptor's own allowed-value list.
+//   2. A bit this build does not name. MM's mode enum grows; a mask carrying an
+//      unfamiliar bit is still a combination the modem advertised and will accept. It
+//      round-trips as `mode-bit-<n>` (the `band-<n>` discipline from `band-names.ts`),
+//      the combination is CLASSIFIED `unknown-combination`, and it stays offerable.
+//      `unknown` is never coerced to `unsupported` — that is the support-claim
+//      taxonomy's first rule, and it applies to a mode catalog exactly as it does to a
+//      capability probe.
+//   3. A member that is not a `(uu)` at all. Dropping it silently shortens the catalog,
+//      so `decodeSupportedModeCombinations` RETAINS it in a separate `undecodable`
+//      list. Decoded + undecodable always equals what the provider sent.
+//
+// This module is pure and total: no transport, no clock, no I/O. The `SetCurrentModes`
+// call itself stays where every other radio mutation lives (`backend/mm-mutations.ts`).
+/**
+ * `MM_MODEM_MODE_NONE` (0) — the modem expresses no preference within its allowed set.
+ * A legal, load-bearing value; never a stand-in for "not reported".
+ */
+export const MODE_NONE = 'none';
+/** `MM_MODEM_MODE_ANY` (0xFFFFFFFF) — every mode the modem has. */
+export const MODE_ANY = 'any';
+const MODE_ANY_VALUE = 0xffffffff;
+/** The named `MMModemMode` bits, in MM's own bit order. */
+const NAMED_BITS = [
+    [1 << 0, 'cs'],
+    [1 << 1, '2g'],
+    [1 << 2, '3g'],
+    [1 << 3, '4g'],
+    [1 << 4, '5g'],
+];
+const BIT_TO_NAME = new Map(NAMED_BITS);
+const NAME_TO_BIT = new Map(NAMED_BITS.map(([bit, name]) => [name, bit]));
+/** The passthrough spelling for a mode bit this build does not name. */
+const PASSTHROUGH_RE = /^mode-bit-(\d+)$/;
+const NAMED_MASK = NAMED_BITS.reduce((mask, [bit]) => mask | bit, 0);
+/** Decode one `MMModemMode` bit. Total: an unnamed bit round-trips. */
+export function modeName(bit) {
+    return BIT_TO_NAME.get(bit) ?? `mode-bit-${bit}`;
+}
+/** Encode one mode name. `undefined` for a name this build cannot place. */
+export function modeValue(name) {
+    if (name === MODE_NONE)
+        return 0;
+    if (name === MODE_ANY)
+        return MODE_ANY_VALUE;
+    const known = NAME_TO_BIT.get(name);
+    if (known !== undefined)
+        return known;
+    const passthrough = PASSTHROUGH_RE.exec(name);
+    if (passthrough?.[1] === undefined)
+        return undefined;
+    const parsed = Number(passthrough[1]);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+/** True when this build recognises the name (a `mode-bit-<n>` passthrough does not). */
+export function isNamedMode(name) {
+    return name === MODE_NONE || name === MODE_ANY || NAME_TO_BIT.has(name);
+}
+/**
+ * Split a mask into its set bits, named where this build can and passed through where
+ * it cannot. A zero mask is the EMPTY set — the caller decides whether that reads as
+ * `none` (a preference) or as an anomaly (an allowed set nothing can be chosen from).
+ */
+export function modeNames(mask) {
+    if (!Number.isSafeInteger(mask) || mask <= 0)
+        return [];
+    if (mask === MODE_ANY_VALUE)
+        return [MODE_ANY];
+    const names = [];
+    for (let bit = 1; bit <= mask && bit > 0; bit *= 2) {
+        if ((mask & bit) !== 0)
+            names.push(modeName(bit));
+    }
+    return names;
+}
+/** Encode a set of mode names into one mask. Fails closed on an unplaceable name. */
+export function encodeModeNames(names) {
+    let mask = 0;
+    for (const name of names) {
+        const value = modeValue(name);
+        if (value === undefined)
+            return { ok: false, unknown: name };
+        mask |= value;
+    }
+    return { ok: true, mask: mask >>> 0 };
+}
+/** Why a combination could not be fully placed. Never a reason to hide it. */
+export const MODE_COMBINATION_ANOMALIES = [
+    /** The allowed mask carries a bit this build does not name. */
+    'unnamed-allowed-bit',
+    /** The preferred mask carries a bit this build does not name. */
+    'unnamed-preferred-bit',
+    /** The preferred mode is not a member of the allowed set. */
+    'preferred-not-in-allowed',
+    /** The preferred mask names more than one mode; MM's contract is at most one. */
+    'preferred-not-singular',
+    /** The allowed mask is zero — nothing can be selected from this combination. */
+    'empty-allowed',
+];
+function isUnnamed(names) {
+    return names.some((name) => !isNamedMode(name));
+}
+/** Build a combination from two raw masks, recording every anomaly it carries. */
+export function modeCombination(allowedMask, preferredMask) {
+    const allowed = modeNames(allowedMask);
+    const preferredNames = modeNames(preferredMask);
+    const anomalies = [];
+    if (allowed.length === 0)
+        anomalies.push('empty-allowed');
+    if (isUnnamed(allowed))
+        anomalies.push('unnamed-allowed-bit');
+    if (isUnnamed(preferredNames))
+        anomalies.push('unnamed-preferred-bit');
+    if (preferredNames.length > 1)
+        anomalies.push('preferred-not-singular');
+    // A zero preferred mask is `none` and is NOT an anomaly: it is MM's own way of
+    // saying "no preference within the allowed set", which the FM350 actually reports.
+    if (preferredNames.length > 0 &&
+        preferredMask !== MODE_ANY_VALUE &&
+        (preferredMask & allowedMask) !== preferredMask) {
+        anomalies.push('preferred-not-in-allowed');
+    }
+    return {
+        allowedMask,
+        allowed,
+        preferredMask,
+        preferred: preferredNames.length === 0 ? MODE_NONE : preferredNames.join('+'),
+        classification: anomalies.length === 0 ? 'named' : 'unknown-combination',
+        anomalies,
+    };
+}
+/** True when the modem stated no preference within this combination's allowed set. */
+export function statesNoPreference(combination) {
+    return combination.preferredMask === 0;
+}
+function decodePair(value) {
+    if (!Array.isArray(value) || value.length !== 2)
+        return undefined;
+    const [allowed, preferred] = value;
+    if (typeof allowed !== 'number' || !Number.isSafeInteger(allowed) || allowed < 0)
+        return undefined;
+    if (typeof preferred !== 'number' || !Number.isSafeInteger(preferred) || preferred < 0) {
+        return undefined;
+    }
+    return [allowed, preferred];
+}
+/** Decode one `CurrentModes` `(uu)`. `undefined` only when the value is not a pair. */
+export function decodeModeCombination(value) {
+    const pair = decodePair(value);
+    return pair === undefined ? undefined : modeCombination(pair[0], pair[1]);
+}
+/**
+ * Decode a `SupportedModes` `a(uu)`.
+ *
+ * Nothing is dropped: a member that is not a pair lands in `undecodable`, and a pair
+ * this build cannot fully name lands in `combinations` classified
+ * `unknown-combination`. A non-array value is an empty catalog, not an error — a modem
+ * that advertises no mode control is a real reading.
+ */
+export function decodeSupportedModeCombinations(value) {
+    if (!Array.isArray(value))
+        return { combinations: [], undecodable: [] };
+    const combinations = [];
+    const undecodable = [];
+    for (const member of value) {
+        const pair = decodePair(member);
+        if (pair === undefined)
+            undecodable.push(member);
+        else
+            combinations.push(modeCombination(pair[0], pair[1]));
+    }
+    return { combinations, undecodable };
+}
+/** True when any advertised combination carries an anomaly this build could not place. */
+export function hasUnknownCombination(set) {
+    return (set.undecodable.length > 0 ||
+        set.combinations.some((each) => each.classification === 'unknown-combination'));
+}
+/** Whether a mask names a mode this build recognises across every set bit. */
+export function isFullyNamedMask(mask) {
+    return mask === MODE_ANY_VALUE || mask === 0 || (mask & ~NAMED_MASK) === 0;
+}

package/dist/radio/mode-truth.d.ts

@@ -0,0 +1,67 @@
+import { type OperationDescriptor } from '../domain/index.js';
+import { type ModeCombination, type ModeCombinationSet, type ModeName } from './mode-combinations.js';
+/**
+ * A mode selection as a caller expresses it: the set to allow, and the one to prefer
+ * within it. `preferred: 'none'` is a first-class selection, not a missing field.
+ */
+export type ModeSelection = {
+    readonly allowed: readonly ModeName[];
+    readonly preferred: ModeName;
+};
+/** `CurrentModes` as a reading — "the modem did not report it" is an answer, not a null. */
+export type ModeCombinationReading = {
+    readonly state: 'reported';
+    readonly combination: ModeCombination;
+} | {
+    readonly state: 'not-reported';
+};
+export type RadioModeTruth = {
+    readonly current: ModeCombinationReading;
+    readonly supported: ModeCombinationSet;
+};
+export declare function readRadioModeTruth(input: {
+    readonly currentModes: unknown;
+    readonly supportedModes: unknown;
+}): RadioModeTruth;
+/** The selection a combination represents, with `preferred` carried across verbatim. */
+export declare function selectionOf(combination: ModeCombination): ModeSelection;
+/** Two selections are the same when both the allowed set AND the preference agree. */
+export declare function sameSelection(left: ModeSelection, right: ModeSelection): boolean;
+/**
+ * The advertised combination a selection names, or `undefined`.
+ *
+ * `undefined` is the whole answer — never the nearest neighbour. `prefer-4g` silently
+ * becoming `prefer-5g` on a marginal cell is the exact substitution
+ * `five-g-preference.ts` refuses, and it is refused here for the same reason.
+ */
+export declare function matchAdvertisedCombination(supported: ModeCombinationSet, selection: ModeSelection): ModeCombination | undefined;
+/** The masks `SetCurrentModes` needs, or the name that could not be placed. */
+export declare function encodeModeSelection(selection: ModeSelection): {
+    readonly ok: true;
+    readonly allowedMask: number;
+    readonly preferredMask: number;
+} | {
+    readonly ok: false;
+    readonly unknown: ModeName;
+};
+export declare const MODE_WRITE_OPERATION_ID = "modemmanager.mode-combination";
+/** Why a mode write is not on offer right now. */
+export type ModeWriteRefusal = 'mode-write-unsupported' | 'no-advertised-mode-combinations';
+export type ModeWriteDescriptorInput = {
+    readonly provider: string;
+    readonly profile: string;
+    readonly truth: RadioModeTruth;
+    readonly writeSupported: boolean;
+};
+/**
+ * The live mode-write descriptor.
+ *
+ * `constraints` is an `allowed-values` list built from the modem's OWN catalog, so a
+ * combination carrying `preferred: 'none'` reaches a consumer through the descriptor
+ * exactly as the modem stated it. Readback is REQUIRED: `SetCurrentModes` returning
+ * without an error only proves the daemon accepted the call, and an
+ * accepted-but-ignored mode write is indistinguishable from success at the call site.
+ */
+export declare function buildModeWriteDescriptor(input: ModeWriteDescriptorInput): OperationDescriptor<ModeSelection, RadioModeTruth>;
+/** True when the modem advertises at least one combination stating no preference. */
+export declare function advertisesNoPreference(truth: RadioModeTruth): boolean;

package/dist/radio/mode-truth.js

@@ -0,0 +1,112 @@
+// What the modem says it can do with its modes, and the operation descriptor built
+// from exactly that — nothing added, nothing narrowed.
+//
+// `capability/five-g-preference.ts` maps four named POSTURES onto an (allowed,
+// preferred) pair and refuses to name one the modem never advertised. This module is
+// the layer underneath it: the modem's own catalog, unedited, so a posture selector
+// and a raw combination selector are reading the same truth. It deliberately does not
+// know what a posture is.
+//
+// THE OFFERED SET IS THE ADVERTISED SET. A combination classified
+// `unknown-combination` — an unfamiliar mode bit, a preferred mode outside its own
+// allowed set — is STILL offered, because the modem advertised it and will accept it.
+// Hiding it would be coercing `unknown` into `unsupported`, which is the one thing
+// `support-claim.ts` exists to stop.
+import { defineOperationDescriptor } from '../domain/index.js';
+import { decodeModeCombination, decodeSupportedModeCombinations, encodeModeNames, MODE_NONE, statesNoPreference, } from './mode-combinations.js';
+export function readRadioModeTruth(input) {
+    const current = decodeModeCombination(input.currentModes);
+    return {
+        current: current === undefined
+            ? { state: 'not-reported' }
+            : { state: 'reported', combination: current },
+        supported: decodeSupportedModeCombinations(input.supportedModes),
+    };
+}
+/** The selection a combination represents, with `preferred` carried across verbatim. */
+export function selectionOf(combination) {
+    return { allowed: combination.allowed, preferred: combination.preferred };
+}
+function sameNameSet(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const sorted = [...right].sort();
+    return [...left].sort().every((name, index) => name === sorted[index]);
+}
+/** Two selections are the same when both the allowed set AND the preference agree. */
+export function sameSelection(left, right) {
+    return left.preferred === right.preferred && sameNameSet(left.allowed, right.allowed);
+}
+/**
+ * The advertised combination a selection names, or `undefined`.
+ *
+ * `undefined` is the whole answer — never the nearest neighbour. `prefer-4g` silently
+ * becoming `prefer-5g` on a marginal cell is the exact substitution
+ * `five-g-preference.ts` refuses, and it is refused here for the same reason.
+ */
+export function matchAdvertisedCombination(supported, selection) {
+    return supported.combinations.find((each) => sameSelection(selectionOf(each), selection));
+}
+/** The masks `SetCurrentModes` needs, or the name that could not be placed. */
+export function encodeModeSelection(selection) {
+    const allowed = encodeModeNames(selection.allowed);
+    if (!allowed.ok)
+        return allowed;
+    const preferred = encodeModeNames(selection.preferred === MODE_NONE ? [] : [selection.preferred]);
+    if (!preferred.ok)
+        return preferred;
+    return { ok: true, allowedMask: allowed.mask, preferredMask: preferred.mask };
+}
+export const MODE_WRITE_OPERATION_ID = 'modemmanager.mode-combination';
+/**
+ * The live mode-write descriptor.
+ *
+ * `constraints` is an `allowed-values` list built from the modem's OWN catalog, so a
+ * combination carrying `preferred: 'none'` reaches a consumer through the descriptor
+ * exactly as the modem stated it. Readback is REQUIRED: `SetCurrentModes` returning
+ * without an error only proves the daemon accepted the call, and an
+ * accepted-but-ignored mode write is indistinguishable from success at the call site.
+ */
+export function buildModeWriteDescriptor(input) {
+    const values = input.truth.supported.combinations.map(selectionOf);
+    const refusal = !input.writeSupported
+        ? 'mode-write-unsupported'
+        : values.length === 0
+            ? 'no-advertised-mode-combinations'
+            : undefined;
+    return defineOperationDescriptor({
+        id: MODE_WRITE_OPERATION_ID,
+        support: {
+            read: { supported: true },
+            write: input.writeSupported
+                ? { supported: true }
+                : { supported: false, reason: 'mode-write-unsupported' },
+        },
+        authority: 'provider',
+        provider: input.provider,
+        constraints: { kind: 'allowed-values', values },
+        livePreconditions: [
+            'modem-present',
+            'runtime-interface-present',
+            'mode-combination-advertised',
+        ],
+        availability: refusal === undefined ? { state: 'available' } : { state: 'refused', reason: refusal },
+        mutationImpact: 'disruptive',
+        retryClass: 'never',
+        readback: {
+            required: true,
+            reason: 'mode-write-readback',
+            matches: (selection, observed) => observed.current.state === 'reported' &&
+                sameSelection(selectionOf(observed.current.combination), selection),
+        },
+        rollback: { required: false },
+        journal: { required: true, reason: 'disruptive-radio-write' },
+        admission: { required: true, reason: 'provider-mutation' },
+        evidence: { profiles: [input.profile], firmware: [] },
+        confidence: 'high',
+    });
+}
+/** True when the modem advertises at least one combination stating no preference. */
+export function advertisesNoPreference(truth) {
+    return truth.supported.combinations.some(statesNoPreference);
+}

package/dist/redact.d.ts

@@ -0,0 +1,15 @@
+/** The marker substituted for every redacted value. */
+export declare const REDACTED = "[redacted]";
+/** Whole-key SMS-content test, case- and separator-insensitive. */
+export declare function isSmsSensitiveKey(key: string): boolean;
+/** Whole-key USSD-content test, case- and separator-insensitive. */
+export declare function isUssdSensitiveKey(key: string): boolean;
+/** Whole-key own-number test, case-, separator- and dot-insensitive. */
+export declare function isOwnNumberSensitiveKey(key: string): boolean;
+/**
+ * Return a deep copy of `value` with every sensitive field redacted. Plain objects
+ * and arrays are walked recursively; all other values (primitives, and opaque
+ * objects like `Date` / `Set` / `Map`) are returned unchanged. The input is never
+ * mutated.
+ */
+export declare function redact(value: unknown): unknown;