@ceralive/modem-control 1.0.0 → 1.2.0

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

@@ -0,0 +1,216 @@
+// The certified USB-mode transition transaction.
+//
+// A mode switch is destructive: the modem physically re-enumerates, its interface
+// name changes, and MM briefly loses sight of it. This transaction runs the switch
+// through A3.3's shared per-modem `ModemActor` (keyed on stableKey, so it serialises
+// behind every other disruptive op) in a FIXED order:
+//
+//   1 NM-quiesce → 2 inhibit-by-cached-UID → 3 AT command → 3b catalog `applyCommand`
+//   (only for a SKU whose AT command writes NV without re-enumerating) → 4 expected
+//   port-drop → 5 uninhibit → 6 await SAME physical UID → 7 POSTCONDITION →
+//   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. 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, 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';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const DEFAULT_WATCHDOG_MS = 30_000;
+const DEFAULT_REENUM_TIMEOUT_MS = 60_000;
+const DEFAULT_POLL_INTERVAL_MS = 250;
+function defaultResolveIfname(device) {
+    return device.ifname !== undefined && device.ifname !== ''
+        ? deviceIfname(device.ifname)
+        : undefined;
+}
+/** The USB-mode transition transaction. One instance is reusable across requests. */
+export class UsbModeTransition {
+    #actor;
+    #nm;
+    #modemManager;
+    #atSender;
+    #enumerate;
+    #interlock;
+    #catalog;
+    #audit;
+    #resolveIfname;
+    #watchdogMs;
+    #reenumMs;
+    #pollMs;
+    constructor(deps) {
+        this.#actor = deps.actor;
+        this.#nm = deps.nm;
+        this.#modemManager = deps.modemManager;
+        this.#atSender = deps.atSender;
+        this.#enumerate = deps.enumerate;
+        this.#interlock = deps.interlock ?? ALLOW_ALL_TRANSITION_INTERLOCK;
+        this.#catalog = deps.catalog ?? CERTIFIED_CATALOG;
+        this.#audit = deps.audit;
+        this.#resolveIfname = deps.resolveIfname ?? defaultResolveIfname;
+        this.#watchdogMs = deps.watchdogMs ?? DEFAULT_WATCHDOG_MS;
+        this.#reenumMs = deps.reenumerationTimeoutMs ?? DEFAULT_REENUM_TIMEOUT_MS;
+        this.#pollMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    }
+    /** Run one transition. Preconditions are checked at entry, then again in-actor. */
+    async execute(request) {
+        const steps = [];
+        // ENTRY check — a doomed request NEVER enters the actor (TIER A: zero calls).
+        const entry = await checkTransitionPreconditions(request, this.#catalog, this.#interlock);
+        if (!entry.ok) {
+            return { status: 'refused', stage: 'entry', reason: entry.reason, steps };
+        }
+        return this.#actor.run(request.stableKey, () => this.#inActor(request, steps));
+    }
+    async #inActor(request, steps) {
+        steps.push('actor-enter');
+        // IN-ACTOR re-check — catches a race that closed a gate while queued (TIER B).
+        const recheck = await checkTransitionPreconditions(request, this.#catalog, this.#interlock);
+        if (!recheck.ok) {
+            return { status: 'refused', stage: 'in-actor', reason: recheck.reason, steps };
+        }
+        const hold = await this.#interlock.hold({ stableKey: request.stableKey });
+        try {
+            return await this.#runTransaction(request, recheck.allowlistedCommands, recheck.plan, steps);
+        }
+        finally {
+            steps.push('release-interlock');
+            await hold.release().catch(() => undefined);
+        }
+    }
+    async #runTransaction(request, allowlistedCommands, plan, steps) {
+        let inhibit;
+        let reactivated = false;
+        const forceUninhibit = async () => {
+            if (inhibit === undefined) {
+                return;
+            }
+            const held = inhibit;
+            inhibit = undefined;
+            steps.push('force-uninhibit');
+            await this.#modemManager.uninhibit(held).catch(() => undefined);
+        };
+        const lease = new AtCommandLease({
+            sender: this.#atSender,
+            allowlist: computeAtAllowlist(allowlistedCommands),
+            timeoutMs: this.#watchdogMs,
+            onWatchdog: forceUninhibit,
+            ...(this.#audit !== undefined ? { audit: this.#audit } : {}),
+        });
+        steps.push('nm-quiesce');
+        const quiesce = await this.#nm.acquireQuiesceLease(request.connectionId, request.deviceIfname);
+        try {
+            steps.push('inhibit');
+            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(plan.atCommand, { inhibitUid: request.inhibitUid });
+            if (plan.applyCommand !== undefined) {
+                steps.push('apply-command');
+                await lease.run(plan.applyCommand, { inhibitUid: request.inhibitUid });
+            }
+            steps.push('await-port-drop');
+            await this.#awaitPortDrop(request.cachedPhysicalUid);
+            steps.push('uninhibit');
+            if (inhibit !== undefined) {
+                const held = inhibit;
+                inhibit = undefined;
+                await this.#modemManager.uninhibit(held);
+            }
+            steps.push('await-reenumeration');
+            const device = await this.#awaitReenumeration(request.cachedPhysicalUid);
+            steps.push('postcondition');
+            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);
+            if (newIfname === undefined) {
+                return { status: 'failed', degraded: true, reason: 'could not resolve new ifname', steps };
+            }
+            steps.push('reactivate');
+            await this.#nm.activate(request.connectionId, newIfname);
+            reactivated = true;
+            return { status: 'succeeded', newIfname, steps };
+        }
+        catch (error) {
+            await forceUninhibit();
+            await this.#reprobe();
+            return {
+                status: 'failed',
+                degraded: true,
+                reason: error instanceof Error ? error.message : String(error),
+                steps,
+            };
+        }
+        finally {
+            await forceUninhibit();
+            if (!reactivated) {
+                // Failure path: restore the old connection. On success the new-ifname
+                // activation supersedes the quiesce lease (old ifname is gone).
+                steps.push('release-quiesce');
+                await this.#nm.releaseQuiesceLease(quiesce).catch(() => undefined);
+            }
+        }
+    }
+    async #awaitPortDrop(uid) {
+        const deadline = Date.now() + this.#reenumMs;
+        while (Date.now() < deadline) {
+            const devices = await this.#enumerate();
+            if (!devices.some((d) => d.physicalUid === uid)) {
+                return;
+            }
+            await sleep(this.#pollMs);
+        }
+        throw new Error(`control port did not drop within ${this.#reenumMs}ms (uid ${uid})`);
+    }
+    async #awaitReenumeration(uid) {
+        const deadline = Date.now() + this.#reenumMs;
+        while (Date.now() < deadline) {
+            const devices = await this.#enumerate();
+            const device = devices.find((d) => d.physicalUid === uid);
+            if (device !== undefined) {
+                return device;
+            }
+            await sleep(this.#pollMs);
+        }
+        throw new Error(`device did not re-enumerate within ${this.#reenumMs}ms (uid ${uid})`);
+    }
+    /** Best-effort state re-read after a crash — the transaction still fails degraded. */
+    async #reprobe() {
+        await this.#enumerate().then(() => undefined, () => undefined);
+    }
+}

package/dist/band/band-names.d.ts

@@ -0,0 +1,42 @@
+/** A band as every operator-facing surface spells it. Opaque; compare by equality. */
+export type BandName = string;
+/** `MM_MODEM_BAND_UNKNOWN`. Never a member of a supported/current set we act on. */
+export declare const BAND_UNKNOWN = "unknown";
+/**
+ * `MM_MODEM_BAND_ANY` (256) — "let the modem choose", i.e. the reset value.
+ * Setting exactly this is how a band lock is released; there is no separate
+ * ModemManager verb for it.
+ */
+export declare const BAND_ANY = "any";
+/** Decode one `MMModemBand` value. Total: an unknown value round-trips. */
+export declare function bandName(value: number): BandName;
+/** Encode one band name. `undefined` for a name this build cannot place. */
+export declare function bandValue(name: BandName): number | undefined;
+/** True when this build recognises the name (a `band-<n>` passthrough does not). */
+export declare function isNamedBand(name: BandName): boolean;
+/**
+ * Decode a `SupportedBands` / `CurrentBands` property value.
+ *
+ * Non-numeric members are DROPPED rather than coerced — a malformed member says
+ * nothing about the radio, and coercing it would invent a band. `unknown` is
+ * dropped for the same reason: MM emits it for "the modem did not say", which is
+ * not a band an operator can select.
+ */
+export declare function decodeBandList(value: unknown): readonly BandName[];
+/**
+ * Encode a band selection for `SetCurrentBands`.
+ *
+ * FAILS CLOSED AS A WHOLE. One unplaceable name rejects the entire request
+ * rather than silently narrowing the selection: a partial band set is a
+ * DIFFERENT lock from the one the operator asked for, and applying it would
+ * strand the radio on bands they never chose.
+ */
+export declare function encodeBandList(names: readonly BandName[]): {
+    readonly ok: true;
+    readonly values: number[];
+} | {
+    readonly ok: false;
+    readonly unknown: BandName;
+};
+/** True when the selection is exactly the reset value (`any`, alone). */
+export declare function isResetSelection(names: readonly BandName[]): boolean;

package/dist/band/band-names.js

@@ -0,0 +1,150 @@
+// MMModemBand ↔ band NAME, in both directions.
+//
+// The D-Bus surface speaks numbers: `Modem.SupportedBands` and
+// `Modem.CurrentBands` are `au`, and `Modem.SetCurrentBands` takes `au`. Every
+// operator-facing surface — mmcli's `--set-current-bands`, this package's API,
+// CeraUI's selector — speaks the NAME (`eutran-3`, `utran-1`, `egsm`, `any`).
+// One mapping, here, so the two can never disagree.
+//
+// WHERE THE NUMBERS COME FROM. ModemManager's `MMModemBand` (`mm-enums.h`) is
+// two different things stitched together, and this module reproduces exactly
+// that shape rather than flattening it into one big table:
+//
+//   * the GSM/UTRAN block (1..20) is IRREGULAR — `UTRAN_2` is 12 while `UTRAN_6`
+//     is 8 — because MM appended bands in the order they were needed, so it is
+//     an explicit table and can only ever be an explicit table;
+//   * every later block is ARITHMETIC, by MM's own construction: `EUTRAN_n` is
+//     `30 + n`, `CDMA_BCn` is `128 + n`, `NGRAN_n` is `300 + n`.
+//
+// Deriving the arithmetic blocks rather than transcribing ~350 constants is the
+// point: a transcription is where a wrong band number would hide, and a wrong
+// band number sets a radio to a band the SIM's network does not operate on.
+//
+// A value this module does not recognise is NEVER dropped and NEVER guessed at.
+// It round-trips as `band-<value>`, so an unfamiliar band a future ModemManager
+// reports is still shown to the operator, still comparable, and still settable —
+// the same "unknown is an answer about the read" discipline `detect.ts` follows.
+/** `MM_MODEM_BAND_UNKNOWN`. Never a member of a supported/current set we act on. */
+export const BAND_UNKNOWN = 'unknown';
+/**
+ * `MM_MODEM_BAND_ANY` (256) — "let the modem choose", i.e. the reset value.
+ * Setting exactly this is how a band lock is released; there is no separate
+ * ModemManager verb for it.
+ */
+export const BAND_ANY = 'any';
+const BAND_ANY_VALUE = 256;
+/**
+ * The irregular head of the enum (`MM_MODEM_BAND_EGSM` = 1 … `G810` = 20),
+ * transcribed because it cannot be derived.
+ */
+const IRREGULAR = {
+    0: BAND_UNKNOWN,
+    1: 'egsm',
+    2: 'dcs',
+    3: 'pcs',
+    4: 'g850',
+    5: 'utran-1',
+    6: 'utran-3',
+    7: 'utran-4',
+    8: 'utran-6',
+    9: 'utran-5',
+    10: 'utran-8',
+    11: 'utran-9',
+    12: 'utran-2',
+    13: 'utran-7',
+    14: 'g450',
+    15: 'g480',
+    16: 'g750',
+    17: 'g380',
+    18: 'g410',
+    19: 'g710',
+    20: 'g810',
+    [BAND_ANY_VALUE]: BAND_ANY,
+};
+/** Arithmetic blocks: `[prefix, base, firstIndex, lastIndex]`. */
+const ARITHMETIC = [
+    // MM_MODEM_BAND_EUTRAN_1 = 31 … EUTRAN_71 = 101.
+    ['eutran-', 30, 1, 71],
+    // MM_MODEM_BAND_CDMA_BC0 = 128 … CDMA_BC19 = 147.
+    ['cdma-bc', 128, 0, 19],
+    // MM_MODEM_BAND_NGRAN_1 = 301 … the 5G NR block.
+    ['ngran-', 300, 1, 261],
+];
+const NUMBER_TO_NAME = new Map();
+const NAME_TO_NUMBER = new Map();
+for (const [value, name] of Object.entries(IRREGULAR)) {
+    NUMBER_TO_NAME.set(Number(value), name);
+    NAME_TO_NUMBER.set(name, Number(value));
+}
+for (const [prefix, base, first, last] of ARITHMETIC) {
+    for (let index = first; index <= last; index += 1) {
+        const name = `${prefix}${index}`;
+        NUMBER_TO_NAME.set(base + index, name);
+        NAME_TO_NUMBER.set(name, base + index);
+    }
+}
+/** The passthrough spelling for a band value this build does not name. */
+const PASSTHROUGH_RE = /^band-(\d+)$/;
+/** Decode one `MMModemBand` value. Total: an unknown value round-trips. */
+export function bandName(value) {
+    return NUMBER_TO_NAME.get(value) ?? `band-${value}`;
+}
+/** Encode one band name. `undefined` for a name this build cannot place. */
+export function bandValue(name) {
+    const known = NAME_TO_NUMBER.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 : undefined;
+}
+/** True when this build recognises the name (a `band-<n>` passthrough does not). */
+export function isNamedBand(name) {
+    return NAME_TO_NUMBER.has(name);
+}
+/**
+ * Decode a `SupportedBands` / `CurrentBands` property value.
+ *
+ * Non-numeric members are DROPPED rather than coerced — a malformed member says
+ * nothing about the radio, and coercing it would invent a band. `unknown` is
+ * dropped for the same reason: MM emits it for "the modem did not say", which is
+ * not a band an operator can select.
+ */
+export function decodeBandList(value) {
+    if (!Array.isArray(value))
+        return [];
+    const names = [];
+    for (const member of value) {
+        if (typeof member !== 'number' || !Number.isSafeInteger(member))
+            continue;
+        const name = bandName(member);
+        if (name === BAND_UNKNOWN)
+            continue;
+        names.push(name);
+    }
+    return names;
+}
+/**
+ * Encode a band selection for `SetCurrentBands`.
+ *
+ * FAILS CLOSED AS A WHOLE. One unplaceable name rejects the entire request
+ * rather than silently narrowing the selection: a partial band set is a
+ * DIFFERENT lock from the one the operator asked for, and applying it would
+ * strand the radio on bands they never chose.
+ */
+export function encodeBandList(names) {
+    const values = [];
+    for (const name of names) {
+        const value = bandValue(name);
+        if (value === undefined)
+            return { ok: false, unknown: name };
+        values.push(value);
+    }
+    return { ok: true, values };
+}
+/** True when the selection is exactly the reset value (`any`, alone). */
+export function isResetSelection(names) {
+    return names.length === 1 && names[0] === BAND_ANY;
+}

package/dist/band/certification.d.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+/**
+ * The device a certification is about. Firmware is a PREFIX for the same reason
+ * the USB-mode catalog matches one: an entry certifies a firmware FAMILY, and
+ * where the family ends is a per-SKU judgement a reviewer makes, not something a
+ * device can compute.
+ */
+export declare const bandSkuSchema: z.ZodObject<{
+    vidPid: z.ZodString;
+    model: z.ZodString;
+    firmwarePrefix: z.ZodString;
+}, z.core.$strict>;
+export type BandSku = z.infer<typeof bandSkuSchema>;
+export declare const bandProofSchema: z.ZodObject<{
+    supportedRead: z.ZodLiteral<true>;
+    set: z.ZodLiteral<true>;
+    readback: z.ZodLiteral<true>;
+    reset: z.ZodLiteral<true>;
+}, z.core.$strict>;
+/**
+ * All four proofs are `z.literal(true)`, so a HALF-certified entry cannot be
+ * expressed at all. A reviewer with three of four proofs has an uncertified SKU
+ * and the file must say so by omitting it — a `false` field would read as a
+ * catalog row, and a catalog row is what surfaces the control.
+ */
+export declare const bandCertificationEntrySchema: z.ZodObject<{
+    vidPid: z.ZodString;
+    model: z.ZodString;
+    firmwarePrefix: z.ZodString;
+    evidence: z.ZodString;
+    proofs: z.ZodObject<{
+        supportedRead: z.ZodLiteral<true>;
+        set: z.ZodLiteral<true>;
+        readback: z.ZodLiteral<true>;
+        reset: z.ZodLiteral<true>;
+    }, z.core.$strict>;
+    provenBands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type BandCertificationEntry = z.infer<typeof bandCertificationEntrySchema>;
+export declare const bandCertificationCatalogSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    entries: z.ZodArray<z.ZodObject<{
+        vidPid: z.ZodString;
+        model: z.ZodString;
+        firmwarePrefix: z.ZodString;
+        evidence: z.ZodString;
+        proofs: z.ZodObject<{
+            supportedRead: z.ZodLiteral<true>;
+            set: z.ZodLiteral<true>;
+            readback: z.ZodLiteral<true>;
+            reset: z.ZodLiteral<true>;
+        }, z.core.$strict>;
+        provenBands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type BandCertificationCatalog = z.infer<typeof bandCertificationCatalogSchema>;
+/** Parse an untrusted value as a band catalog. Throws with a precise path. */
+export declare function loadBandCertificationCatalog(value: unknown): BandCertificationCatalog;
+/** The catalog shipped in this package, validated at module load. */
+export declare const BAND_CERTIFICATION_CATALOG: BandCertificationCatalog;
+/**
+ * The entry certifying this exact device, or `undefined`.
+ *
+ * All three discriminators must match, and the firmware match is a PREFIX of the
+ * device's FULL revision — never a truncation of the device's revision to the
+ * entry's length, which would certify a family the reviewer never looked at.
+ */
+export declare function findBandCertification(catalog: BandCertificationCatalog, sku: BandSku): BandCertificationEntry | undefined;
+/**
+ * Whether a band-lock control may be OFFERED for this device.
+ *
+ * Fail-closed in every direction: an unknown SKU, a SKU with no entry, and a SKU
+ * whose entry predates a proof step all answer `false`.
+ */
+export declare function isBandControlCertified(catalog: BandCertificationCatalog, sku: BandSku | undefined): boolean;
+/**
+ * Narrow an advertised band set to what the certification proves is settable.
+ *
+ * An entry with no `provenBands` proves the whole advertised set (the drill swept
+ * it); an entry that names bands offers ONLY those, intersected with what the
+ * modem advertises right now — a certified band the device no longer advertises
+ * is not offerable, and the device's own answer outranks the catalog.
+ */
+export declare function offerableBands(entry: BandCertificationEntry | undefined, supported: readonly string[]): readonly string[];

package/dist/band/certification.js

@@ -0,0 +1,127 @@
+// The band-lock certification catalog — what has actually been PROVEN, per SKU.
+//
+// A band lock is the one capability module that can take a working uplink off the
+// air and leave it there: a band the SIM's network does not operate on registers
+// nowhere, and a modem that does not honour a reset leaves the operator with no
+// way back short of a replug they may not be able to reach. So band-lock is
+// deliberately STRICTER than the framework floor in `support-claim.ts`. The
+// framework offers a control at `capable` (the modem advertises the capability)
+// because hiding an uncertified-but-working control puts hardware behind a
+// paperwork gate. For this module the paperwork IS the safety argument, so the
+// control stays HIDDEN until an entry here proves the whole round trip.
+//
+// FOUR STEPS, ALL FOUR REQUIRED, and they are separate booleans rather than one
+// `certified: true` because each can fail on its own and each failure means a
+// different thing:
+//
+//   supportedRead — `SupportedBands` was read and named real bands. Without it
+//                   there is nothing to offer.
+//   set           — `SetCurrentBands` was accepted for a band in that set.
+//   readback      — `CurrentBands` afterwards reported exactly what was asked
+//                   for. An accepted-but-ignored write is the failure mode that
+//                   looks like success from the call site alone.
+//   reset         — setting `any` restored the baseline. This is the escape
+//                   hatch; a SKU that cannot be shown to reset must never be
+//                   locked in the first place.
+//
+// THE SHIPPED CATALOG IS EMPTY, and that is the honest state. Nothing in the
+// fleet has been through the drill — see the phase-C band-lock evidence for why
+// (the bench Quectel's SIM never registers, so "re-registration proven" cannot
+// be claimed today). An entry is added by a human-reviewed commit carrying the
+// bench transcript, exactly like `usb-mode/certified-catalog.json`.
+import { z } from 'zod';
+import rawCatalog from './certified-bands.json' with { type: 'json' };
+/**
+ * The device a certification is about. Firmware is a PREFIX for the same reason
+ * the USB-mode catalog matches one: an entry certifies a firmware FAMILY, and
+ * where the family ends is a per-SKU judgement a reviewer makes, not something a
+ * device can compute.
+ */
+export const bandSkuSchema = z
+    .object({
+    vidPid: z.string().regex(/^[0-9a-f]{4}:[0-9a-f]{4}$/),
+    model: z.string().min(1),
+    firmwarePrefix: z.string().min(1),
+})
+    .strict();
+export const bandProofSchema = z
+    .object({
+    supportedRead: z.literal(true),
+    set: z.literal(true),
+    readback: z.literal(true),
+    reset: z.literal(true),
+})
+    .strict();
+/**
+ * All four proofs are `z.literal(true)`, so a HALF-certified entry cannot be
+ * expressed at all. A reviewer with three of four proofs has an uncertified SKU
+ * and the file must say so by omitting it — a `false` field would read as a
+ * catalog row, and a catalog row is what surfaces the control.
+ */
+export const bandCertificationEntrySchema = z
+    .object({
+    vidPid: z.string().regex(/^[0-9a-f]{4}:[0-9a-f]{4}$/),
+    model: z.string().min(1),
+    firmwarePrefix: z.string().min(1),
+    /** Free-form: where the transcript proving the four steps lives. */
+    evidence: z.string().min(1),
+    proofs: bandProofSchema,
+    /**
+     * Bands the reviewer proved were individually settable AND resettable.
+     * An EMPTY list means "the whole advertised set", which is what a drill
+     * that swept the set records; a non-empty list NARROWS what is offered.
+     */
+    provenBands: z.array(z.string()).default([]),
+})
+    .strict();
+export const bandCertificationCatalogSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    entries: z.array(bandCertificationEntrySchema),
+})
+    .strict();
+/** Parse an untrusted value as a band catalog. Throws with a precise path. */
+export function loadBandCertificationCatalog(value) {
+    return bandCertificationCatalogSchema.parse(value);
+}
+/** The catalog shipped in this package, validated at module load. */
+export const BAND_CERTIFICATION_CATALOG = loadBandCertificationCatalog(rawCatalog);
+/**
+ * The entry certifying this exact device, or `undefined`.
+ *
+ * All three discriminators must match, and the firmware match is a PREFIX of the
+ * device's FULL revision — never a truncation of the device's revision to the
+ * entry's length, which would certify a family the reviewer never looked at.
+ */
+export function findBandCertification(catalog, sku) {
+    return catalog.entries.find((entry) => entry.vidPid === sku.vidPid &&
+        entry.model === sku.model &&
+        sku.firmwarePrefix.startsWith(entry.firmwarePrefix));
+}
+/**
+ * Whether a band-lock control may be OFFERED for this device.
+ *
+ * Fail-closed in every direction: an unknown SKU, a SKU with no entry, and a SKU
+ * whose entry predates a proof step all answer `false`.
+ */
+export function isBandControlCertified(catalog, sku) {
+    if (sku === undefined)
+        return false;
+    return findBandCertification(catalog, sku) !== undefined;
+}
+/**
+ * Narrow an advertised band set to what the certification proves is settable.
+ *
+ * An entry with no `provenBands` proves the whole advertised set (the drill swept
+ * it); an entry that names bands offers ONLY those, intersected with what the
+ * modem advertises right now — a certified band the device no longer advertises
+ * is not offerable, and the device's own answer outranks the catalog.
+ */
+export function offerableBands(entry, supported) {
+    if (entry === undefined)
+        return [];
+    if (entry.provenBands.length === 0)
+        return supported;
+    const proven = new Set(entry.provenBands);
+    return supported.filter((band) => proven.has(band));
+}

package/dist/band/certified-bands.json

@@ -0,0 +1,4 @@
+{
+    "schemaVersion": 1,
+    "entries": []
+}

package/dist/band/index.d.ts

@@ -0,0 +1,2 @@
+export * from './band-names.js';
+export * from './certification.js';

package/dist/band/index.js

@@ -0,0 +1,8 @@
+// The band-lock capability module: the MMModemBand vocabulary and the
+// certification catalog that gates whether a control may be offered at all.
+//
+// The D-Bus verbs themselves live with the other ModemManager mutations
+// (`backend/mm-mutations.ts`), declared on `ModemManagerPort` — a band change is
+// a radio mutation like a mode change, not a subsystem of its own.
+export * from './band-names.js';
+export * from './certification.js';