@ceralive/modem-control 1.0.0 → 1.2.0

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;

package/dist/redact.js

@@ -0,0 +1,189 @@
+// Redaction — strip sensitive identifiers from any value before it is logged,
+// serialized into a receipt, or written to a bundle.
+//
+// The sensitive CLASSES (draft §Oracle #1, round-5 auth semantics): ICCID, IMSI,
+// EID, SIM PIN, SIM PUK, and APN / connection passwords, PLUS the GNSS coordinate
+// class below. Redaction is KEY-BASED and RECURSIVE: it walks nested objects and
+// arrays and replaces the value under any sensitive key with a fixed marker, no
+// matter how deep — e.g. a password at `policy.connection.auth.password`, or an
+// `iccid` inside an array of SIM slots.
+/** The marker substituted for every redacted value. */
+export const REDACTED = '[redacted]';
+// Leaf key names carrying a sensitive value, matched case-insensitively. The match
+// is EXACT (or exact on the last dotted segment), so NM-style keys like
+// `gsm.password` are caught while non-secret siblings like `gsm.password-flags`
+// (a "0"/"4" flag, not a secret) are not.
+const SENSITIVE_KEYS = new Set([
+    'iccid',
+    'imsi',
+    'eid',
+    'imei',
+    'equipmentidentifier',
+    'equipment-identifier',
+    'equipment_identifier',
+    'pin',
+    'pin2',
+    'newpin',
+    'puk',
+    'puk2',
+    'password',
+    'passwd',
+    'subscriptionid',
+]);
+// GNSS coordinate keys. A fix says where the operator physically is, so it is
+// sensitive for a reason none of the keys above share, and it gets its own set so
+// the privacy fence stays readable: the GPS module keeps a fix in memory for a
+// live display and NEVER persists, uploads, or logs one.
+//
+// Scoped to a GNSS fix on purpose. `3gpp-lac-ci` (coarse cell location) is NOT
+// here — it is the existing cell-info module's deliberate, separately-gated output,
+// and silently blanking it would break a surface that already ships.
+const LOCATION_KEYS = new Set([
+    'latitude',
+    'longitude',
+    'altitude',
+    'lat',
+    'lon',
+    'lng',
+    'nmea',
+    'nmeasentences',
+    'coordinates',
+]);
+/**
+ * SMS content is its own key class, and it may NOT be folded into
+ * `SENSITIVE_KEYS` above. That set matches a leaf name exactly (or the last
+ * dotted segment), so adding `text` / `number` / `sender` to it would redact
+ * every unrelated `text` and `number` in the package — a receipt's reason text,
+ * a slot number, a signal reading. These keys are matched WHOLE after case- AND
+ * separator-folding, so only a key that genuinely names message content or an
+ * originator is scrubbed.
+ *
+ * A message body routinely carries a one-time code (the bench SIM's inbox holds
+ * a literal "Tu pin es: …") and a sender number identifies the subscriber, so
+ * both are treated exactly like a PIN: never rendered anywhere.
+ *
+ * This mirrors CeraUI's `isSmsSensitiveKey` (`helpers/logger.ts`) key-for-key.
+ * It is a Rule-D MIRROR, never a shared import — the two halves are kept honest
+ * by their tests, not by a path.
+ */
+const SMS_SENSITIVE_KEYS = new Set([
+    'smstext',
+    'smsbody',
+    'smsfrom',
+    'smssender',
+    'smsnumber',
+    'messagetext',
+    'messagebody',
+    'msisdn',
+    'sender',
+    'sms.content.text',
+    'sms.content.number',
+]);
+/** Whole-key SMS-content test, case- and separator-insensitive. */
+export function isSmsSensitiveKey(key) {
+    return SMS_SENSITIVE_KEYS.has(key.toLowerCase().replace(/[_-]/g, ''));
+}
+/**
+ * USSD carrier text — its own class, for the same reason SMS is: `reply`,
+ * `command`, and `response` are far too common to redact by leaf name, so these
+ * are matched WHOLE after case- and separator-folding.
+ *
+ * BOTH DIRECTIONS are sensitive, not just the reply. A USSD dialogue is how a
+ * subscriber tops up a prepaid line, so the COMMAND routinely carries a voucher
+ * code (`*123*<16 digits>#`) and the reply carries a balance, a subscriber
+ * number, or a one-time code. `NetworkNotification` / `NetworkRequest` are
+ * ModemManager's own property names for network-initiated USSD text and are
+ * included so a raw property dump cannot leak what the call path masks.
+ *
+ * This is why the USSD module names its carrier-text fields `ussdCommand`,
+ * `ussdResponse`, and `ussdReply` rather than the shorter names that read better:
+ * redaction here is key-based, so the FIELD NAME is the guarantee.
+ */
+const USSD_SENSITIVE_KEYS = new Set([
+    'ussd',
+    'ussdcommand',
+    'ussdreply',
+    'ussdresponse',
+    'ussdtext',
+    'networknotification',
+    'networkrequest',
+]);
+/** Whole-key USSD-content test, case- and separator-insensitive. */
+export function isUssdSensitiveKey(key) {
+    return USSD_SENSITIVE_KEYS.has(key.toLowerCase().replace(/[_-]/g, ''));
+}
+/**
+ * The SIM's OWN number (MSISDN) — its own class, matched WHOLE after case-,
+ * separator- AND dot-folding so ModemManager's `Modem.OwnNumbers` and mmcli's
+ * `modem.generic.own-numbers` are both caught by one rule.
+ *
+ * It cannot join `SENSITIVE_KEYS`: that set matches a leaf name, and `number` /
+ * `numbers` are far too common — a slot number and a band count would both
+ * vanish. `msisdn` stays in the SMS set (its historical home) and is not
+ * duplicated here.
+ *
+ * It is DISPLAYED to the operator behind an explicit reveal. That is a
+ * rendering decision about a surface the subscriber already owns; it does not
+ * make the value loggable, so it is redacted exactly like a PIN.
+ */
+const OWN_NUMBER_SENSITIVE_KEYS = new Set([
+    'ownnumber',
+    'ownnumbers',
+    'phonenumber',
+    'phonenumbers',
+    'simnumber',
+    'subscribernumber',
+    'modemgenericownnumbers',
+    'modemownnumbers',
+]);
+/** Whole-key own-number test, case-, separator- and dot-insensitive. */
+export function isOwnNumberSensitiveKey(key) {
+    return OWN_NUMBER_SENSITIVE_KEYS.has(key.toLowerCase().replace(/[_.-]/g, ''));
+}
+function isSensitiveKey(key) {
+    const lower = key.toLowerCase();
+    if (SENSITIVE_KEYS.has(lower) || LOCATION_KEYS.has(lower)) {
+        return true;
+    }
+    if (isSmsSensitiveKey(key) || isUssdSensitiveKey(key) || isOwnNumberSensitiveKey(key)) {
+        return true;
+    }
+    const dot = lower.lastIndexOf('.');
+    if (dot < 0) {
+        return false;
+    }
+    const leaf = lower.slice(dot + 1);
+    return SENSITIVE_KEYS.has(leaf) || LOCATION_KEYS.has(leaf);
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function redactValue(value, underSensitiveKey) {
+    if (underSensitiveKey) {
+        return REDACTED;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redactValue(item, false));
+    }
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            out[key] = redactValue(child, isSensitiveKey(key));
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * 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 function redact(value) {
+    return redactValue(value, false);
+}

package/dist/safety/composition-root.d.ts

@@ -0,0 +1,28 @@
+import { ModemActor, type QuiesceHook } from '../backend/modem-actor.js';
+import type { PhysicalModemId } from '../domain/index.js';
+import type { MutationAdmissionPort, ResourceOwnershipPort, ResourceOwnershipRequest, ResourceOwnershipResult, UhubctlPort } from '../ports/index.js';
+export declare class CompositionRootAlreadyExistsError extends Error {
+    readonly name = "CompositionRootAlreadyExistsError";
+    constructor();
+}
+export type ModemControlCompositionRootOptions = {
+    readonly admission: MutationAdmissionPort;
+    readonly ownership: ResourceOwnershipPort | undefined;
+    readonly quiesce?: QuiesceHook;
+    readonly uhubctl?: UhubctlPort;
+};
+export declare class ModemControlCompositionRoot {
+    #private;
+    readonly admission: MutationAdmissionPort;
+    readonly ownership: ResourceOwnershipPort;
+    readonly uhubctl: UhubctlPort | undefined;
+    constructor(options: ModemControlCompositionRootOptions);
+    actorFor(modemId: PhysicalModemId): ModemActor;
+    acquireOwnership(request: ResourceOwnershipRequest): Promise<ResourceOwnershipResult>;
+    dispose(): Promise<void>;
+}
+export declare class MissingResourceOwnershipPortError extends Error {
+    readonly name = "MissingResourceOwnershipPortError";
+    constructor();
+}
+export declare function createModemControlCompositionRoot(options: ModemControlCompositionRootOptions): ModemControlCompositionRoot;

package/dist/safety/composition-root.js

@@ -0,0 +1,65 @@
+import { ModemActor } from '../backend/modem-actor.js';
+let compositionRootExists = false;
+export class CompositionRootAlreadyExistsError extends Error {
+    name = 'CompositionRootAlreadyExistsError';
+    constructor() {
+        super('a modem-control composition root already exists in this process');
+    }
+}
+export class ModemControlCompositionRoot {
+    admission;
+    ownership;
+    uhubctl;
+    #quiesce;
+    #actors = new Map();
+    #ownershipLeases = [];
+    #disposed = false;
+    constructor(options) {
+        if (compositionRootExists)
+            throw new CompositionRootAlreadyExistsError();
+        if (options.ownership === undefined)
+            throw new MissingResourceOwnershipPortError();
+        compositionRootExists = true;
+        this.admission = options.admission;
+        this.ownership = options.ownership;
+        this.#quiesce = options.quiesce;
+        this.uhubctl = options.uhubctl;
+    }
+    actorFor(modemId) {
+        const existing = this.#actors.get(modemId);
+        if (existing !== undefined)
+            return existing;
+        const actor = new ModemActor(this.#quiesce);
+        this.#actors.set(modemId, actor);
+        return actor;
+    }
+    async acquireOwnership(request) {
+        const result = await this.ownership.acquire(request);
+        if (result.status === 'acquired')
+            this.#ownershipLeases.push(result.lease);
+        return result;
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        try {
+            for (const lease of this.#ownershipLeases.splice(0).reverse()) {
+                await lease.release();
+            }
+        }
+        finally {
+            this.#actors.clear();
+            compositionRootExists = false;
+        }
+    }
+}
+export class MissingResourceOwnershipPortError extends Error {
+    name = 'MissingResourceOwnershipPortError';
+    constructor() {
+        super('a ResourceOwnershipPort is required; no pass-through default exists');
+    }
+}
+export function createModemControlCompositionRoot(options) {
+    return new ModemControlCompositionRoot(options);
+}