@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/capability/detect.d.ts

@@ -0,0 +1,52 @@
+import type { MmPropertyProbe } from '../backend/features.js';
+import type { RadioAccessTechnology } from '../domain/index.js';
+import type { CapabilityEvidence, CapabilityModule } from './support-claim.js';
+/** MM's Messaging interface — SMS list/read lives here. */
+export declare const MESSAGING_IFACE = "org.freedesktop.ModemManager1.Modem.Messaging";
+/** MM's Location interface — GNSS sources are advertised here. */
+export declare const LOCATION_IFACE = "org.freedesktop.ModemManager1.Modem.Location";
+/** MM's 3GPP USSD interface — the same name the USSD adapter dials. */
+export declare const USSD_IFACE = "org.freedesktop.ModemManager1.Modem.Modem3gpp.Ussd";
+/**
+ * What A3.2 observed, plus the two signals the static object tree cannot carry.
+ *
+ * `interfaces` is the set of interface NAMES exported on the modem object, which
+ * is how SMS/USSD/Location are advertised — they are separate interfaces, not
+ * properties, so `MmPropertyProbe` alone cannot see them.
+ */
+export interface ModuleCapabilityProbe extends MmPropertyProbe {
+    readonly interfaces?: ReadonlySet<string>;
+    /**
+     * `Location.Capabilities` decoded to source names (`gps-raw`, `gps-nmea`, …).
+     * An EMPTY set is a real answer — the interface exists and offers no GNSS.
+     */
+    readonly locationSources?: ReadonlySet<string>;
+    /**
+     * `SupportedModes` decoded to the RAT families it actually names.
+     *
+     * OPTIONAL, and its absence is the pre-existing behaviour verbatim: a caller
+     * that decoded only property NAMES answers exactly as before. Supplying it
+     * strictly NARROWS `five-g-pref`, because the property's mere presence is
+     * equally true of a 4G-only modem — see `detectCapabilityModules`.
+     */
+    readonly supportedRats?: ReadonlySet<RadioAccessTechnology>;
+}
+/**
+ * Detect every module's capability for one modem. Pure, total, never throws.
+ *
+ * `fcc-auto-unlock` is deliberately always `unknown`: FCC unlock is carried out
+ * by a ModemManager PLUGIN keyed on the device, and nothing on the modem's own
+ * D-Bus surface advertises whether one applies. Reporting `absent` would hide the
+ * module on hardware that supports it, and `present` would promise a plugin that
+ * may not be installed — so the honest answer is that this probe cannot tell, and
+ * evidence for it has to come from the catalog instead.
+ *
+ * `five-g-pref` is the one module whose property NAME is not the question. Every
+ * ModemManager modem exports `SupportedModes`, including a 4G-only one, so the
+ * name alone would resolve `present` on hardware with no 5G at all and offer a 5G
+ * posture nothing could honour. When the caller decoded the property's VALUE the
+ * verdict narrows to whether the catalog actually names 5GNR; when it did not,
+ * the property-name answer stands, so this is a strict narrowing and never a new
+ * way to claim a capability.
+ */
+export declare function detectCapabilityModules(probe: ModuleCapabilityProbe): Record<CapabilityModule, CapabilityEvidence>;

package/dist/capability/detect.js

@@ -0,0 +1,86 @@
+// Per-module capability detection — what ONE modem can actually be asked to do.
+//
+// It follows `backend/features.ts` exactly, because the constraints are the same:
+// detection must PROBE the observed surface rather than match a version
+// whitelist, it must never throw, and an unseen future ModemManager must degrade
+// gracefully instead of resolving to a confident wrong answer.
+//
+// The one rule this module adds is that `unknown` is a first-class result. A
+// property set we never observed says nothing about the device, and the ladder in
+// `support-claim.ts` stops at `enabled` for it — surfaced by nothing, mutated by
+// nothing. Answering `absent` there would hide a working capability; answering
+// `present` would offer a control the modem cannot honour.
+import { MODEM_IFACE, MODEM3GPP_USSD_IFACE } from '../backend/constants.js';
+import { fiveGPreferenceEvidence } from './five-g-preference.js';
+/** MM's Messaging interface — SMS list/read lives here. */
+export const MESSAGING_IFACE = `${MODEM_IFACE}.Messaging`;
+/** MM's Location interface — GNSS sources are advertised here. */
+export const LOCATION_IFACE = `${MODEM_IFACE}.Location`;
+/** MM's 3GPP USSD interface — the same name the USSD adapter dials. */
+export const USSD_IFACE = MODEM3GPP_USSD_IFACE;
+const GNSS_SOURCES = ['gps-raw', 'gps-nmea', 'gps-unmanaged', 'agps-msa', 'agps-msb'];
+/**
+ * A property we did not see is only evidence of ABSENCE when we saw the object at
+ * all. An empty property set means the read never landed.
+ */
+function fromProperty(probe, name) {
+    if (probe.properties.size === 0) {
+        return 'unknown';
+    }
+    return probe.properties.has(name) ? 'present' : 'absent';
+}
+function fromAnyProperty(probe, names) {
+    if (probe.properties.size === 0) {
+        return 'unknown';
+    }
+    return names.some((name) => probe.properties.has(name)) ? 'present' : 'absent';
+}
+function fromInterface(probe, iface) {
+    if (probe.interfaces === undefined) {
+        return 'unknown';
+    }
+    return probe.interfaces.has(iface) ? 'present' : 'absent';
+}
+function detectGnss(probe) {
+    const iface = fromInterface(probe, LOCATION_IFACE);
+    if (iface !== 'present') {
+        return iface;
+    }
+    // The interface being exported is not the same claim as the modem offering a
+    // GNSS source — MM exports Location for 3GPP-LAC/CID-only devices too.
+    if (probe.locationSources === undefined) {
+        return 'unknown';
+    }
+    return GNSS_SOURCES.some((source) => probe.locationSources?.has(source)) ? 'present' : 'absent';
+}
+/**
+ * Detect every module's capability for one modem. Pure, total, never throws.
+ *
+ * `fcc-auto-unlock` is deliberately always `unknown`: FCC unlock is carried out
+ * by a ModemManager PLUGIN keyed on the device, and nothing on the modem's own
+ * D-Bus surface advertises whether one applies. Reporting `absent` would hide the
+ * module on hardware that supports it, and `present` would promise a plugin that
+ * may not be installed — so the honest answer is that this probe cannot tell, and
+ * evidence for it has to come from the catalog instead.
+ *
+ * `five-g-pref` is the one module whose property NAME is not the question. Every
+ * ModemManager modem exports `SupportedModes`, including a 4G-only one, so the
+ * name alone would resolve `present` on hardware with no 5G at all and offer a 5G
+ * posture nothing could honour. When the caller decoded the property's VALUE the
+ * verdict narrows to whether the catalog actually names 5GNR; when it did not,
+ * the property-name answer stands, so this is a strict narrowing and never a new
+ * way to claim a capability.
+ */
+export function detectCapabilityModules(probe) {
+    return {
+        'band-lock': fromProperty(probe, 'SupportedBands'),
+        sms: fromInterface(probe, MESSAGING_IFACE),
+        'five-g-pref': probe.supportedRats === undefined
+            ? fromProperty(probe, 'SupportedModes')
+            : fiveGPreferenceEvidence(probe.supportedRats),
+        'fcc-auto-unlock': 'unknown',
+        gps: detectGnss(probe),
+        ussd: fromInterface(probe, USSD_IFACE),
+        esim: fromAnyProperty(probe, ['SimType', 'EsimStatus']),
+    };
+}

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

@@ -0,0 +1,104 @@
+import type { RadioAccessTechnology } from '../domain/index.js';
+import type { CapabilityEvidence } from './support-claim.js';
+/**
+ * The postures this module offers. Deliberately four NAMED intents rather than a
+ * free (allowed, preferred) pair: an arbitrary pair is expressible on the wire but
+ * not answerable by an operator, and most pairs are postures nobody wants.
+ *
+ *   5g-only   — allow ONLY 5G. No fallback: out of 5G coverage the modem stops
+ *               registering, which is why it is offered but never a default.
+ *   prefer-5g — allow 5G and everything below it, rank 5G first.
+ *   prefer-4g — the SAME allowed set, ranked LTE first. This is the posture a
+ *               marginal 5G cell calls for, and the one the coarse allowed-set
+ *               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 type FiveGPreference = (typeof FIVE_G_PREFERENCES)[number];
+/** One `(allowed, preferred)` pair, the shape MM's `CurrentModes` really carries. */
+export interface RadioModeSet {
+    readonly allowed: ReadonlySet<RadioAccessTechnology>;
+    /** MM's `preferred` is a SINGLE mode, and `none` is a legal answer. */
+    readonly preferred?: RadioAccessTechnology | undefined;
+}
+/** What a stated preference resolves to, in `MmMutations.setRadioModes`'s shape. */
+export interface FiveGRadioTarget {
+    readonly preferenceOrdered: readonly RadioAccessTechnology[];
+    readonly allowedSet: ReadonlySet<RadioAccessTechnology>;
+}
+/**
+ * SA vs NSA — and the honest answer, which is that ModemManager does not expose
+ * the choice at all.
+ *
+ * Checked against MM 1.24.2's own D-Bus surface rather than recalled: the only
+ * NR-specific member on a modem object is
+ * `Modem.Modem3gpp.SetNr5gRegistrationSettings`, whose keys are `mico-mode` and
+ * `drx-cycle` — power-saving registration parameters, not a standalone-vs
+ * non-standalone selector. Vendors expose the selector through their own AT
+ * commands (Quectel `AT+QNWPREFCFG="mode_pref"`, and one per vendor after that),
+ * which is a per-SKU control surface this module deliberately does not open: an
+ * uncertified AT write that can cost registration is exactly what the evidence
+ * gate exists to keep out.
+ *
+ * So the axis is REPORTED as unsupported rather than omitted. A missing field
+ * 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 interface NrModeSelection {
+    readonly supported: false;
+    readonly reason: typeof NR_MODE_UNSUPPORTED_REASON;
+}
+/** The SA/NSA verdict. Constant today, and a function so a future SKU-certified
+ *  path replaces one call site rather than every consumer. */
+export declare function nrModeSelection(): NrModeSelection;
+/**
+ * Does this modem's advertised mode catalog contain 5G?
+ *
+ * An EMPTY catalog is `unknown`, never `absent` — an unobserved read says nothing
+ * about the device, and reporting `absent` there would hide the module on a modem
+ * that supports it. This is the same first-class-`unknown` rule `detect.ts`
+ * follows, applied one level deeper: `detect.ts` can only see that a
+ * `SupportedModes` property EXISTS, which is equally true of a 4G-only modem.
+ */
+export declare function fiveGPreferenceEvidence(supportedRats: ReadonlySet<RadioAccessTechnology> | undefined): CapabilityEvidence;
+/**
+ * Which postures this modem can actually be asked for.
+ *
+ * A modem with no 5G is offered NOTHING — not `5g-off` either, because "turn 5G
+ * off" is a control that would change nothing on a radio that has no 5G, and a
+ * control that cannot change anything is the defect this repo's evidence gate
+ * exists to keep off an operator's screen.
+ *
+ * `prefer-5g` / `prefer-4g` / `5g-off` each additionally require a SUB-5G mode to
+ * fall back to: on a 5G-only radio they would all collapse onto the same allowed
+ * set as `5g-only`, i.e. three labels for one posture.
+ */
+export declare function offeredFiveGPreferences(supportedRats: ReadonlySet<RadioAccessTechnology> | undefined): readonly FiveGPreference[];
+/**
+ * Resolve a stated preference into the `(allowed, preferred)` pair to write.
+ *
+ * `undefined` means this modem cannot express the posture — the caller must
+ * REFUSE rather than substitute a neighbouring one. Substituting is how an
+ * operator asks for "prefer 4G" on a marginal cell and silently gets 5G-first.
+ */
+export declare function fiveGPreferenceToRadio(preference: FiveGPreference, supportedRats: ReadonlySet<RadioAccessTechnology> | undefined): FiveGRadioTarget | undefined;
+/**
+ * Which posture a modem's CURRENT modes name — or `undefined` for a pair this
+ * model does not name.
+ *
+ * `undefined` is a first-class answer and must not be rounded to the nearest
+ * posture: a radio parked on `allowed: 3g,4g; preferred: 3g` is in a state no 5G
+ * preference describes, and reporting one would show an operator a selection they
+ * never made and cannot get back to.
+ */
+export declare function readFiveGPreference(current: RadioModeSet | undefined): FiveGPreference | undefined;
+/**
+ * Did a readback land on the requested posture?
+ *
+ * The RESULT of the write is not the write's own acknowledgement — MM answering
+ * the method call says the request was accepted, not that the radio took it, and
+ * a modem is entitled to clamp a mode set it cannot honour. So a confirmation is
+ * a re-read compared against the request, and this is that comparison.
+ */
+export declare function fiveGPreferenceConfirmed(requested: FiveGPreference, readback: RadioModeSet | undefined): boolean;

package/dist/capability/five-g-preference.js

@@ -0,0 +1,171 @@
+// The `five-g-pref` capability module's MODEL — which 5G postures a modem can be
+// asked for, how each maps onto ModemManager's `SetCurrentModes`, and which one
+// the radio is on right now.
+//
+// It is pure and total. Nothing here talks to a bus: `MmMutations.setRadioModes`
+// already owns the D-Bus call, the per-modem serialization and the quiesce, so
+// this module's whole job is to decide WHICH `DesiredRadio` a stated preference
+// means and to refuse to name one the modem never advertised.
+//
+// WHY THE MODULE EXISTS AT ALL, given the 3G/4G/5G selector already writes
+// `SetCurrentModes`: that selector's vocabulary is the ALLOWED SET. Two genuinely
+// different postures — "allow 4G and 5G, prefer 5G" and "allow 4G and 5G, prefer
+// 4G" — share one allowed set and are distinguishable only by the PREFERRED mode,
+// which the coarse selector folds away. An operator on a marginal 5G cell wants
+// exactly that distinction, and it is the one thing they could not previously ask
+// for.
+/**
+ * The postures this module offers. Deliberately four NAMED intents rather than a
+ * free (allowed, preferred) pair: an arbitrary pair is expressible on the wire but
+ * not answerable by an operator, and most pairs are postures nobody wants.
+ *
+ *   5g-only   — allow ONLY 5G. No fallback: out of 5G coverage the modem stops
+ *               registering, which is why it is offered but never a default.
+ *   prefer-5g — allow 5G and everything below it, rank 5G first.
+ *   prefer-4g — the SAME allowed set, ranked LTE first. This is the posture a
+ *               marginal 5G cell calls for, and the one the coarse allowed-set
+ *               selector structurally cannot express.
+ *   5g-off    — allow everything the modem supports EXCEPT 5G.
+ */
+export const FIVE_G_PREFERENCES = ['5g-only', 'prefer-5g', 'prefer-4g', '5g-off'];
+/**
+ * SA vs NSA — and the honest answer, which is that ModemManager does not expose
+ * the choice at all.
+ *
+ * Checked against MM 1.24.2's own D-Bus surface rather than recalled: the only
+ * NR-specific member on a modem object is
+ * `Modem.Modem3gpp.SetNr5gRegistrationSettings`, whose keys are `mico-mode` and
+ * `drx-cycle` — power-saving registration parameters, not a standalone-vs
+ * non-standalone selector. Vendors expose the selector through their own AT
+ * commands (Quectel `AT+QNWPREFCFG="mode_pref"`, and one per vendor after that),
+ * which is a per-SKU control surface this module deliberately does not open: an
+ * uncertified AT write that can cost registration is exactly what the evidence
+ * gate exists to keep out.
+ *
+ * So the axis is REPORTED as unsupported rather than omitted. A missing field
+ * reads as "nobody asked"; a stated `not-exposed-by-modemmanager` tells an
+ * operator looking for an SA toggle why there is none.
+ */
+export const NR_MODE_UNSUPPORTED_REASON = 'not-exposed-by-modemmanager';
+/** The SA/NSA verdict. Constant today, and a function so a future SKU-certified
+ *  path replaces one call site rather than every consumer. */
+export function nrModeSelection() {
+    return { supported: false, reason: NR_MODE_UNSUPPORTED_REASON };
+}
+/** RAT ranking, highest generation first. The ONE ordering this module uses. */
+const RAT_ORDER = ['5gnr', 'lte', 'umts', 'gsm'];
+function ranked(rats) {
+    return RAT_ORDER.filter((rat) => rats.has(rat));
+}
+/**
+ * Does this modem's advertised mode catalog contain 5G?
+ *
+ * An EMPTY catalog is `unknown`, never `absent` — an unobserved read says nothing
+ * about the device, and reporting `absent` there would hide the module on a modem
+ * that supports it. This is the same first-class-`unknown` rule `detect.ts`
+ * follows, applied one level deeper: `detect.ts` can only see that a
+ * `SupportedModes` property EXISTS, which is equally true of a 4G-only modem.
+ */
+export function fiveGPreferenceEvidence(supportedRats) {
+    if (supportedRats === undefined || supportedRats.size === 0) {
+        return 'unknown';
+    }
+    return supportedRats.has('5gnr') ? 'present' : 'absent';
+}
+/**
+ * Which postures this modem can actually be asked for.
+ *
+ * A modem with no 5G is offered NOTHING — not `5g-off` either, because "turn 5G
+ * off" is a control that would change nothing on a radio that has no 5G, and a
+ * control that cannot change anything is the defect this repo's evidence gate
+ * exists to keep off an operator's screen.
+ *
+ * `prefer-5g` / `prefer-4g` / `5g-off` each additionally require a SUB-5G mode to
+ * fall back to: on a 5G-only radio they would all collapse onto the same allowed
+ * set as `5g-only`, i.e. three labels for one posture.
+ */
+export function offeredFiveGPreferences(supportedRats) {
+    if (supportedRats === undefined || !supportedRats.has('5gnr')) {
+        return [];
+    }
+    const lower = ranked(supportedRats).filter((rat) => rat !== '5gnr');
+    if (lower.length === 0) {
+        return ['5g-only'];
+    }
+    // `prefer-4g` names LTE specifically, so it is offered only on a modem that
+    // has LTE. A 5G+UMTS-only radio is not a real fleet device, but naming a mode
+    // the modem never advertised is the one thing this module must not do.
+    return FIVE_G_PREFERENCES.filter((preference) => preference !== 'prefer-4g' || supportedRats.has('lte'));
+}
+/**
+ * Resolve a stated preference into the `(allowed, preferred)` pair to write.
+ *
+ * `undefined` means this modem cannot express the posture — the caller must
+ * REFUSE rather than substitute a neighbouring one. Substituting is how an
+ * operator asks for "prefer 4G" on a marginal cell and silently gets 5G-first.
+ */
+export function fiveGPreferenceToRadio(preference, supportedRats) {
+    if (supportedRats === undefined || !offeredFiveGPreferences(supportedRats).includes(preference)) {
+        return undefined;
+    }
+    const all = ranked(supportedRats);
+    const withoutNr = all.filter((rat) => rat !== '5gnr');
+    switch (preference) {
+        case '5g-only':
+            return { allowedSet: new Set(['5gnr']), preferenceOrdered: ['5gnr'] };
+        case 'prefer-5g':
+            return { allowedSet: new Set(all), preferenceOrdered: all };
+        case 'prefer-4g':
+            // The allowed set is IDENTICAL to `prefer-5g`'s — only the ranking moves.
+            // That is the whole point of the posture, and it is why a consumer must
+            // never diff allowed sets to decide whether a write is needed.
+            return {
+                allowedSet: new Set(all),
+                preferenceOrdered: ['lte', ...all.filter((rat) => rat !== 'lte')],
+            };
+        case '5g-off':
+            return { allowedSet: new Set(withoutNr), preferenceOrdered: withoutNr };
+    }
+}
+/**
+ * Which posture a modem's CURRENT modes name — or `undefined` for a pair this
+ * model does not name.
+ *
+ * `undefined` is a first-class answer and must not be rounded to the nearest
+ * posture: a radio parked on `allowed: 3g,4g; preferred: 3g` is in a state no 5G
+ * preference describes, and reporting one would show an operator a selection they
+ * never made and cannot get back to.
+ */
+export function readFiveGPreference(current) {
+    if (current === undefined || current.allowed.size === 0) {
+        return undefined;
+    }
+    const has5g = current.allowed.has('5gnr');
+    const others = ranked(current.allowed).filter((rat) => rat !== '5gnr');
+    if (!has5g) {
+        // A sub-5G allowed set is `5g-off` whatever it ranks first: the posture is
+        // about 5G, and this model has no opinion on how 4G and 3G are ordered.
+        return '5g-off';
+    }
+    if (others.length === 0) {
+        return '5g-only';
+    }
+    if (current.preferred === '5gnr') {
+        return 'prefer-5g';
+    }
+    if (current.preferred === 'lte') {
+        return 'prefer-4g';
+    }
+    return undefined;
+}
+/**
+ * Did a readback land on the requested posture?
+ *
+ * The RESULT of the write is not the write's own acknowledgement — MM answering
+ * the method call says the request was accepted, not that the radio took it, and
+ * a modem is entitled to clamp a mode set it cannot honour. So a confirmation is
+ * a re-read compared against the request, and this is that comparison.
+ */
+export function fiveGPreferenceConfirmed(requested, readback) {
+    return readFiveGPreference(readback) === requested;
+}

package/dist/capability/index.d.ts

@@ -0,0 +1,3 @@
+export * from './detect.js';
+export * from './five-g-preference.js';
+export * from './support-claim.js';

package/dist/capability/index.js

@@ -0,0 +1,10 @@
+// Capability-module feature-gate framework — the support-claim taxonomy, the
+// per-modem capability detection the seven gated modules resolve against, and the
+// modules that have landed their own probe + evidence.
+//
+// Implemented so far: `five-g-pref` (`five-g-preference.ts`). The remaining six
+// are framework-only and may not be surfaced or claimed until their own change
+// lands.
+export * from './detect.js';
+export * from './five-g-preference.js';
+export * from './support-claim.js';

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

@@ -0,0 +1,39 @@
+/** The seven gated capability modules. */
+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
+ * rung reached:
+ *
+ *   unavailable — not shipped in this build, OR the modem positively lacks it.
+ *   implemented — shipped, gate OFF. The default for every module, everywhere.
+ *   enabled     — gate ON, capability UNKNOWN. "Not asked" is not "absent".
+ *   capable     — gate ON, modem advertises it. The floor for offering a control.
+ *   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 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';
+export interface SupportClaimInput {
+    readonly implemented: boolean;
+    readonly gateEnabled: boolean;
+    readonly capability: CapabilityEvidence;
+    readonly certified: boolean;
+}
+export declare function resolveSupportClaim(input: SupportClaimInput): SupportClaimState;
+export declare const SURFACEABLE_SUPPORT_STATES: readonly SupportClaimState[];
+export declare function mayRenderModule(state: SupportClaimState): boolean;
+export declare function mayClaimSupport(state: SupportClaimState): boolean;
+export type CapabilityModuleClaims = Readonly<Record<CapabilityModule, SupportClaimState>>;
+export interface CapabilityMatrixInput {
+    readonly implemented: readonly CapabilityModule[];
+    readonly gates: Partial<Record<CapabilityModule, boolean>>;
+    readonly capability: Partial<Record<CapabilityModule, CapabilityEvidence>>;
+    readonly certified?: Partial<Record<CapabilityModule, boolean>>;
+}
+/** Total by construction: every module gets an explicit state. */
+export declare function resolveCapabilityMatrix(input: CapabilityMatrixInput): CapabilityModuleClaims;
+export declare function surfaceableModules(claims: CapabilityModuleClaims): CapabilityModule[];
+export declare function claimableModules(claims: CapabilityModuleClaims): CapabilityModule[];

package/dist/capability/support-claim.js

@@ -0,0 +1,81 @@
+// The support-claim taxonomy — the vocabulary this stack uses to say how much is
+// actually known about a capability module on a given modem.
+//
+// It exists because "supported" was one word doing four jobs: the code exists,
+// an operator turned it on, the modem advertises it, and somebody proved it on
+// this firmware. Those are four different facts with four different consequences
+// — the third gates what a UI may offer, the fourth gates what a support matrix
+// may claim — and collapsing them is how a doc comes to promise a combination
+// nobody ever ran.
+//
+// This module is PURE and mirrors the same ladder CeraUI's `@ceraui/rpc`
+// `capability-modules.schema.ts` carries. It is a mirror rather than a shared
+// import by Rule D: this repo builds standalone, so the two halves are kept
+// honest by their tests, not by a path.
+/** The seven gated capability modules. */
+export const CAPABILITY_MODULES = [
+    'band-lock',
+    'sms',
+    'five-g-pref',
+    'fcc-auto-unlock',
+    'gps',
+    'ussd',
+    'esim',
+];
+/**
+ * The ladder, lowest rung first. `resolveSupportClaim` answers with the highest
+ * rung reached:
+ *
+ *   unavailable — not shipped in this build, OR the modem positively lacks it.
+ *   implemented — shipped, gate OFF. The default for every module, everywhere.
+ *   enabled     — gate ON, capability UNKNOWN. "Not asked" is not "absent".
+ *   capable     — gate ON, modem advertises it. The floor for offering a control.
+ *   certified   — capable AND proven on this exact model+firmware. The ONLY rung
+ *                 a support matrix or a doc may claim.
+ */
+export const SUPPORT_CLAIM_STATES = [
+    'unavailable',
+    'implemented',
+    'enabled',
+    'capable',
+    'certified',
+];
+export function resolveSupportClaim(input) {
+    if (!input.implemented || input.capability === 'absent') {
+        return 'unavailable';
+    }
+    if (!input.gateEnabled) {
+        return 'implemented';
+    }
+    if (input.capability === 'unknown') {
+        return 'enabled';
+    }
+    return input.certified ? 'certified' : 'capable';
+}
+export const SURFACEABLE_SUPPORT_STATES = ['capable', 'certified'];
+export function mayRenderModule(state) {
+    return SURFACEABLE_SUPPORT_STATES.includes(state);
+}
+export function mayClaimSupport(state) {
+    return state === 'certified';
+}
+/** Total by construction: every module gets an explicit state. */
+export function resolveCapabilityMatrix(input) {
+    const implemented = new Set(input.implemented);
+    const claims = {};
+    for (const module of CAPABILITY_MODULES) {
+        claims[module] = resolveSupportClaim({
+            implemented: implemented.has(module),
+            gateEnabled: input.gates[module] === true,
+            capability: input.capability[module] ?? 'unknown',
+            certified: input.certified?.[module] === true,
+        });
+    }
+    return claims;
+}
+export function surfaceableModules(claims) {
+    return CAPABILITY_MODULES.filter((module) => mayRenderModule(claims[module]));
+}
+export function claimableModules(claims) {
+    return CAPABILITY_MODULES.filter((module) => mayClaimSupport(claims[module]));
+}

package/dist/domain/brand.d.ts

@@ -0,0 +1,10 @@
+declare const brand: unique symbol;
+/** A primitive `T` tagged with a compile-time-only brand `B`. Erased at runtime. */
+export type Brand<T, B extends string> = T & {
+    readonly [brand]: B;
+};
+/** Assert a value is a non-empty string, throwing a typed error otherwise. */
+export declare function nonEmptyString(value: string, label: string): string;
+/** Assert a value is a non-negative safe integer, throwing a typed error otherwise. */
+export declare function nonNegativeInteger(value: number, label: string): number;
+export {};

package/dist/domain/brand.js

@@ -0,0 +1,21 @@
+// Nominal (branded) primitive types for the domain layer.
+//
+// Branding stops the four identity strings — and the two counter numbers — from
+// being interchangeable at the type level: a `LogicalSlotId` can never be passed
+// where a `SubscriptionId` is expected, even though both are strings at runtime.
+// Downstream waves (A2.2 ports, A3.x D-Bus backend) depend on this distinction.
+import { DomainError } from './errors.js';
+/** Assert a value is a non-empty string, throwing a typed error otherwise. */
+export function nonEmptyString(value, label) {
+    if (value.length === 0) {
+        throw new DomainError(`${label} must be a non-empty string`);
+    }
+    return value;
+}
+/** Assert a value is a non-negative safe integer, throwing a typed error otherwise. */
+export function nonNegativeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new DomainError(`${label} must be a non-negative safe integer, got ${value}`);
+    }
+    return value;
+}

package/dist/domain/errors.d.ts

@@ -0,0 +1,32 @@
+/** Base class for every domain-layer error. Callers can catch this to trap all. */
+export declare class DomainError extends Error {
+    readonly name: string;
+    constructor(message: string);
+}
+/**
+ * Every distinct impossible cross-dimension combination the guards reject.
+ * One code per rule so a failing construction names exactly what it violated.
+ */
+export type ImpossibleStateCode = 'registered-while-absent' | 'registered-radio-off' | 'registered-empty-rat-set' | 'active-state-while-absent' | 'radio-off-while-active' | 'nm-activated-while-absent' | 'nm-activated-without-interface' | 'nm-activated-without-mm-connected' | 'multiple-active-sim-slots' | 'locked-sim-in-empty-slot' | 'mm-locked-without-sim-lock' | 'data-interface-name-without-presence' | 'recovery-attempts-negative' | 'recovery-cooldown-stage-mismatch' | 'recovery-idle-with-attempts';
+/** A snapshot was constructed (or transitioned into) a physically impossible state. */
+export declare class ImpossibleStateError extends DomainError {
+    readonly name = "ImpossibleStateError";
+    readonly code: ImpossibleStateCode;
+    constructor(code: ImpossibleStateCode, detail: string);
+}
+/**
+ * A durable policy binding was attempted against an identity that is not allowed
+ * to carry one — today only low-confidence (ambiguous) equipment identities.
+ */
+export declare class PolicyBindingRefusedError extends DomainError {
+    readonly name = "PolicyBindingRefusedError";
+    readonly reason: 'ambiguous-identity';
+    constructor(detail: string);
+}
+/** A snapshot transition tried to keep or lower the monotonic revision. */
+export declare class RevisionMonotonicityError extends DomainError {
+    readonly name = "RevisionMonotonicityError";
+    readonly previous: number;
+    readonly next: number;
+    constructor(previous: number, next: number);
+}