@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/backend/recovery-ladder.js

@@ -0,0 +1,116 @@
+// The evidence-gated recovery ladder — disabled by default.
+//
+// A bounded four-rung ladder [1 nm-cycle: NM deactivate→reactivate exact pair; 2
+// mm-cycle: MM disable→enable; 3 reset: MM Reset(); 4 power-cycle: power hook (only
+// `none` → always unsupported)]. Every disruptive rung routes through A3.3's shared
+// per-modem `ModemActor` (serialised behind all other disruptive ops) and consults
+// the `LifecycleInterlock` first so it never disrupts a streaming modem. GATES, in
+// order: recovery.enabled=false → zero steps · attribution≠modem-fault → zero steps ·
+// budget spent / cooldown → zero steps · per-rung allowDisruptive · interlock.
+// Disabled or un-attributed, NOT ONE side-effecting call is made.
+import { ALLOW_ALL_INTERLOCK } from './lifecycle-interlock.js';
+import { NONE_POWER_HOOK } from './power-contract.js';
+import { beginAttempt, DEFAULT_RECOVERY_BUDGET, INITIAL_BUDGET_STATE, markRecovered, } from './recovery-budget.js';
+export const LADDER_ORDER = ['nmCycle', 'mmCycle', 'reset', 'powerCycle'];
+const ALLOW = { allowDisruptive: true };
+/** Default config: every rung permitted, default budget. */
+export const DEFAULT_LADDER_CONFIG = {
+    nmCycle: ALLOW,
+    mmCycle: ALLOW,
+    reset: ALLOW,
+    powerCycle: ALLOW,
+    budget: DEFAULT_RECOVERY_BUDGET,
+};
+/**
+ * The recovery ladder. Holds per-modem budget state keyed by stable key so the
+ * loop-stop can latch a flapping modem `degraded` across invocations.
+ */
+export class RecoveryLadder {
+    #actor;
+    #steps;
+    #powerHook;
+    #interlock;
+    #config;
+    #states = new Map();
+    constructor(deps) {
+        this.#actor = deps.actor;
+        this.#steps = deps.steps;
+        this.#powerHook = deps.powerHook ?? NONE_POWER_HOOK;
+        this.#interlock = deps.interlock ?? ALLOW_ALL_INTERLOCK;
+        this.#config = deps.config ?? DEFAULT_LADDER_CONFIG;
+    }
+    /** The current budget state for a modem (for observability / assertions). */
+    budgetStateFor(stableKey) {
+        return this.#states.get(stableKey) ?? INITIAL_BUDGET_STATE;
+    }
+    /** Clear a modem's budget / degraded latch (operator un-degrade). */
+    clear(stableKey) {
+        this.#states.delete(stableKey);
+    }
+    /** Run one recovery attempt. Enforces every gate before any side effect. */
+    async run(recovery, request) {
+        const { stableKey, attribution } = request;
+        // GATE 1 — master switch. Disabled ⇒ literally zero steps, zero side effects.
+        if (!recovery.enabled) {
+            return this.#end('disabled', request, [], 'recovery disabled by policy');
+        }
+        // GATE 2 — attribution. Only a confident modem-fault may ever be disruptive.
+        if (attribution !== 'modem-fault') {
+            return this.#end('not-attributed', request, [], `attribution '${attribution}' is never disruptive`);
+        }
+        // GATE 3 — budget / cooldown / loop-stop.
+        const decision = beginAttempt(this.budgetStateFor(stableKey), this.#config.budget, request.now);
+        if (decision.kind === 'loop-stop') {
+            this.#states.set(stableKey, decision.state);
+            return this.#end('loop-stop', request, [], 'recovery budget exhausted — modem marked degraded');
+        }
+        if (decision.kind === 'cooldown') {
+            return this.#end('cooldown', request, [], 'within cooldown window — attempt refused');
+        }
+        this.#states.set(stableKey, decision.state);
+        return this.#runRungs(request);
+    }
+    async #runRungs(request) {
+        const { stableKey } = request;
+        const context = { stableKey, modem: request.modem, at: request.now };
+        const steps = [];
+        for (const rung of LADDER_ORDER) {
+            if (!this.#config[rung].allowDisruptive) {
+                steps.push({ rung, status: 'skipped', reason: 'allowDisruptive is false' });
+                continue;
+            }
+            // Interlock BEFORE any disruptive step — never disrupt a streaming modem.
+            const verdict = await this.#interlock.canDisrupt({ stableKey });
+            if (!verdict.allow) {
+                steps.push({ rung, status: 'blocked', reason: verdict.reason });
+                return this.#end('interlock-blocked', request, steps, `interlock blocked '${rung}': ${verdict.reason}`);
+            }
+            const report = await this.#runRung(rung, context);
+            steps.push(report);
+            if (report.status === 'applied' && (await request.probeHealthy())) {
+                this.#states.set(stableKey, markRecovered());
+                return this.#end('recovered', request, steps, `recovered at rung '${rung}'`);
+            }
+        }
+        return this.#end('exhausted', request, steps, 'ladder exhausted without restoring health');
+    }
+    async #runRung(rung, context) {
+        if (rung === 'powerCycle') {
+            const result = await this.#powerHook.cycle({ stableKey: context.stableKey, at: context.at });
+            return { rung, status: result.status, reason: result.reason };
+        }
+        // Rungs 1–3 route through the shared per-modem actor for serialisation.
+        const step = this.#steps[rung];
+        const outcome = await this.#actor.run(context.stableKey, () => step(context));
+        return { rung, status: outcome.status, reason: outcome.reason };
+    }
+    #end(kind, request, steps, reason) {
+        return {
+            kind,
+            attribution: request.attribution,
+            steps,
+            degraded: this.budgetStateFor(request.stableKey).degraded,
+            reason,
+        };
+    }
+}

package/dist/backend/router-ethernet.d.ts

@@ -0,0 +1,19 @@
+import { type EpochMillis } from '../domain/index.js';
+import type { DeviceIfname, RouterPort } from '../ports/index.js';
+/** Injectable probes — each defaults to a `Bun.spawn` shell-out; all advisory. */
+export interface RouterEthernetProbeDeps {
+    readonly now?: () => EpochMillis;
+    /** Whether `ifname` exists and is administratively up. */
+    readonly checkLinkUp?: (ifname: DeviceIfname) => Promise<boolean>;
+    /** The DHCP-assigned default gateway on `ifname`, if any. */
+    readonly resolveGateway?: (ifname: DeviceIfname) => Promise<string | undefined>;
+    /** Whether `host` is reachable via `ifname` (ICMP). */
+    readonly ping?: (host: string, ifname: DeviceIfname) => Promise<boolean>;
+}
+/**
+ * Create a router-ethernet probe implementing the advisory `RouterPort`. Presence is
+ * link-up; health additionally reports DHCP-gateway reachability and a basic egress
+ * probe — all informational, never a gate. `checkHealth` swallows every error into a
+ * `false` field so it can never throw.
+ */
+export declare function createRouterEthernetProbe(deps?: RouterEthernetProbeDeps): RouterPort;

package/dist/backend/router-ethernet.js

@@ -0,0 +1,66 @@
+// Generic router-ethernet detection — presence, DHCP-gateway reachability, and a
+// basic egress-health probe for uplinks ModemManager cannot control (HiLink, RNDIS
+// tether, full router firmware).
+//
+// EVERYTHING here is ADVISORY (ports/router.ts, matrix §1-R): health degradation is
+// informational only. `checkHealth` NEVER throws and NEVER gates anything — a
+// degraded router stays in the routing set; the controller merely reports what it
+// observed. Each probe is an injectable seam (default `Bun.spawn` of `ip` / `ping`)
+// so tests run with no real network.
+import { epochMillis } from '../domain/index.js';
+/** The host used for the basic egress-health probe (public DNS anycast). */
+const EGRESS_PROBE_HOST = '1.1.1.1';
+async function spawnSucceeds(command) {
+    try {
+        const proc = Bun.spawn([...command], { stdout: 'pipe', stderr: 'pipe' });
+        return (await proc.exited) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function spawnOutput(command) {
+    try {
+        const proc = Bun.spawn([...command], { stdout: 'pipe', stderr: 'pipe' });
+        const [out, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+        return code === 0 ? out : '';
+    }
+    catch {
+        return '';
+    }
+}
+function defaultCheckLinkUp(ifname) {
+    return spawnSucceeds(['ip', 'link', 'show', 'up', 'dev', String(ifname)]);
+}
+async function defaultResolveGateway(ifname) {
+    // `ip -o route show default dev <ifname>` → "default via 192.168.8.1 dev <ifname> …".
+    const out = await spawnOutput(['ip', '-o', 'route', 'show', 'default', 'dev', String(ifname)]);
+    const match = out.match(/default via (\S+)/);
+    return match?.[1];
+}
+function defaultPing(host, ifname) {
+    return spawnSucceeds(['ping', '-c', '1', '-W', '2', '-I', String(ifname), host]);
+}
+/**
+ * Create a router-ethernet probe implementing the advisory `RouterPort`. Presence is
+ * link-up; health additionally reports DHCP-gateway reachability and a basic egress
+ * probe — all informational, never a gate. `checkHealth` swallows every error into a
+ * `false` field so it can never throw.
+ */
+export function createRouterEthernetProbe(deps = {}) {
+    const now = deps.now ?? (() => epochMillis(Date.now()));
+    const checkLinkUp = deps.checkLinkUp ?? defaultCheckLinkUp;
+    const resolveGateway = deps.resolveGateway ?? defaultResolveGateway;
+    const ping = deps.ping ?? defaultPing;
+    async function probePresence(ifname) {
+        return (await checkLinkUp(ifname).catch(() => false)) ? 'present' : 'absent';
+    }
+    async function checkHealth(ifname) {
+        const presence = await probePresence(ifname);
+        const gateway = presence === 'present' ? await resolveGateway(ifname).catch(() => undefined) : undefined;
+        const gatewayReachable = gateway !== undefined && (await ping(gateway, ifname).catch(() => false));
+        const egressHealthy = gatewayReachable && (await ping(EGRESS_PROBE_HOST, ifname).catch(() => false));
+        return { presence, gatewayReachable, egressHealthy, observedAt: now() };
+    }
+    return { probePresence, checkHealth };
+}

package/dist/backend/row-store.d.ts

@@ -0,0 +1,13 @@
+import type { ObservationFailureReason, ObservationList } from '../ports/index.js';
+import type { DecodedManagedObjects } from './managed-objects.js';
+export declare class ObservationRowStore {
+    #private;
+    /** Reconcile the authoritative tree into the rows. Returns whether rows changed.
+     *  This is the SOLE removal path — an omission from a current-epoch snapshot. */
+    reconcile(tree: DecodedManagedObjects): boolean;
+    /** Mark the source healthy after a successful reconcile. Returns whether health flipped. */
+    markHealthy(): boolean;
+    /** Flag every row stale (retained, never removed). Returns whether an emission is due. */
+    markUnavailable(reason: ObservationFailureReason): boolean;
+    list(): ObservationList;
+}

package/dist/backend/row-store.js

@@ -0,0 +1,82 @@
+// The observer's row bookkeeping — revisions, source health, and the discriminated
+// list result — split out of the observer so each file stays focused.
+//
+// Removal lives ONLY in `reconcile`: a modem is dropped exactly when a current-epoch
+// authoritative snapshot omits it. `markUnavailable` never removes — it flags rows
+// stale and retains them, so the `ObservationList` failure arm always carries its rows.
+import { createSnapshot, revision as makeRevision, markSourceUnavailable, } from '../domain/index.js';
+import { fingerprint, mapModem, modemPaths } from './mapping.js';
+export class ObservationRowStore {
+    #rows = new Map();
+    #revCounter = 0;
+    #sourceHealthy = false;
+    #failureReason = 'not-started';
+    /** Reconcile the authoritative tree into the rows. Returns whether rows changed.
+     *  This is the SOLE removal path — an omission from a current-epoch snapshot. */
+    reconcile(tree) {
+        let changed = false;
+        const seen = new Set();
+        for (const path of modemPaths(tree)) {
+            seen.add(path);
+            if (this.#upsert(path, mapModem(tree, path))) {
+                changed = true;
+            }
+        }
+        for (const path of [...this.#rows.keys()]) {
+            if (!seen.has(path)) {
+                this.#rows.delete(path);
+                changed = true;
+            }
+        }
+        return changed;
+    }
+    /** Mark the source healthy after a successful reconcile. Returns whether health flipped. */
+    markHealthy() {
+        const flipped = !this.#sourceHealthy;
+        this.#sourceHealthy = true;
+        return flipped;
+    }
+    /** Flag every row stale (retained, never removed). Returns whether an emission is due. */
+    markUnavailable(reason) {
+        const wasHealthy = this.#sourceHealthy;
+        let changed = false;
+        for (const [path, row] of this.#rows) {
+            if (row.snapshot.sourceHealth === 'sourceUnavailable') {
+                continue;
+            }
+            this.#rows.set(path, {
+                snapshot: markSourceUnavailable(row.snapshot),
+                fingerprint: row.fingerprint,
+            });
+            changed = true;
+        }
+        this.#sourceHealthy = false;
+        this.#failureReason = reason;
+        return changed || wasHealthy;
+    }
+    list() {
+        const rows = [...this.#rows.values()].map((row) => row.snapshot);
+        if (this.#sourceHealthy) {
+            return { ok: true, rows };
+        }
+        return { ok: false, reason: this.#failureReason, rows };
+    }
+    #upsert(path, mapped) {
+        const fp = fingerprint(mapped);
+        const existing = this.#rows.get(path);
+        if (existing !== undefined &&
+            existing.fingerprint === fp &&
+            existing.snapshot.sourceHealth === 'live') {
+            return false;
+        }
+        this.#rows.set(path, {
+            snapshot: createSnapshot({ ...mapped, revision: this.#nextRevision() }),
+            fingerprint: fp,
+        });
+        return true;
+    }
+    #nextRevision() {
+        this.#revCounter += 1;
+        return makeRevision(this.#revCounter);
+    }
+}

package/dist/backend/signal-setup.d.ts

@@ -0,0 +1,30 @@
+import type { DbusTransport } from '../transport/index.js';
+import type { DecodedManagedObjects } from './managed-objects.js';
+/** Whether periodic signal reporting is configured for a modem. */
+export type SignalCadence = 'active' | 'unsupported' | 'unknown';
+/** MM's default reporting rate is seconds; callers pass whole seconds. */
+export declare const DEFAULT_SIGNAL_INTERVAL_SECONDS = 5;
+export interface SignalSetupManagerOptions {
+    readonly transport: DbusTransport;
+    /** MM bus name override (defaults to `org.freedesktop.ModemManager1`). */
+    readonly destination?: string;
+    /** Reporting interval in seconds passed to `Signal.Setup`. */
+    readonly intervalSeconds?: number;
+}
+/**
+ * Drives `Signal.Setup` across the modem fleet, keyed to the observer's epochs. Feed
+ * it every `onEpochRefresh` event; it applies setup to each modem exactly once per
+ * epoch, re-applies to survivors on a new epoch, and never calls for an old one.
+ */
+export declare class SignalSetupManager {
+    #private;
+    constructor(options: SignalSetupManagerOptions);
+    /** The last-known cadence for a modem path (`'unknown'` until first applied). */
+    cadenceFor(modemPath: string): SignalCadence;
+    /**
+     * Apply `Signal.Setup` for the current epoch's modems. New epoch ⇒ every survivor
+     * is re-applied; an already-applied (epoch, modem) is skipped. Modems absent from
+     * this snapshot keep their last cadence but are not re-driven.
+     */
+    applyForEpoch(epoch: string, tree: DecodedManagedObjects): void;
+}

package/dist/backend/signal-setup.js

@@ -0,0 +1,92 @@
+// Signal.Setup(interval) full-lifecycle management, epoch-scoped.
+//
+// ModemManager's `Modem.Signal.Setup(rate)` turns on periodic extended signal
+// reporting. Its lifecycle mirrors the observer's epochs (A3.1):
+//
+//   - applied once when the backend starts observing a modem;
+//   - applied to a hot-plugged modem the moment it appears (`InterfacesAdded`);
+//   - RE-APPLIED to every surviving modem after every owner-epoch change (a fresh MM
+//     owner has none of the previous owner's cadence configured);
+//   - NEVER applied for an OLD epoch — a setup scheduled for an epoch that is no
+//     longer current is dropped before the call ever goes out.
+//
+// A modem that lacks the `Modem.Signal` interface entirely reports
+// `signalCadence: 'unsupported'` and is never called — a soft capability gap, never
+// a start failure. The manager is driven purely by the observer's `onEpochRefresh`
+// hook: every current-epoch snapshot re-drives it, and it de-dupes per (epoch, modem)
+// so a modem is set up exactly once per epoch.
+import { MM_BUS_NAME, MODEM_IFACE } from './constants.js';
+import { hasInterface, pathsWithInterface } from './managed-objects.js';
+/** The `Modem.Signal` interface — absent means signal cadence is unsupported. */
+const SIGNAL_IFACE = 'org.freedesktop.ModemManager1.Modem.Signal';
+/** MM's default reporting rate is seconds; callers pass whole seconds. */
+export const DEFAULT_SIGNAL_INTERVAL_SECONDS = 5;
+/**
+ * Drives `Signal.Setup` across the modem fleet, keyed to the observer's epochs. Feed
+ * it every `onEpochRefresh` event; it applies setup to each modem exactly once per
+ * epoch, re-applies to survivors on a new epoch, and never calls for an old one.
+ */
+export class SignalSetupManager {
+    #transport;
+    #destination;
+    #interval;
+    #currentEpoch;
+    // Guards double-issue within an epoch: `${epoch}\u0000${modemPath}`.
+    #applied = new Set();
+    #cadence = new Map();
+    constructor(options) {
+        this.#transport = options.transport;
+        this.#destination = options.destination ?? MM_BUS_NAME;
+        this.#interval = options.intervalSeconds ?? DEFAULT_SIGNAL_INTERVAL_SECONDS;
+    }
+    /** The last-known cadence for a modem path (`'unknown'` until first applied). */
+    cadenceFor(modemPath) {
+        return this.#cadence.get(modemPath) ?? 'unknown';
+    }
+    /**
+     * Apply `Signal.Setup` for the current epoch's modems. New epoch ⇒ every survivor
+     * is re-applied; an already-applied (epoch, modem) is skipped. Modems absent from
+     * this snapshot keep their last cadence but are not re-driven.
+     */
+    applyForEpoch(epoch, tree) {
+        this.#currentEpoch = epoch;
+        for (const modemPath of pathsWithInterface(tree, MODEM_IFACE)) {
+            const key = `${epoch}\u0000${modemPath}`;
+            if (this.#applied.has(key)) {
+                continue;
+            }
+            this.#applied.add(key);
+            void this.#setupOne(epoch, modemPath, tree);
+        }
+    }
+    async #setupOne(epoch, modemPath, tree) {
+        // Epoch changed out from under us before we could issue the call — drop it, so
+        // no Signal.Setup ever fires for a superseded epoch.
+        if (this.#currentEpoch !== epoch) {
+            return;
+        }
+        if (!hasInterface(tree, modemPath, SIGNAL_IFACE)) {
+            this.#cadence.set(modemPath, 'unsupported');
+            return;
+        }
+        if (this.#currentEpoch !== epoch) {
+            return;
+        }
+        try {
+            await this.#transport.callMethod({
+                destination: this.#destination,
+                path: modemPath,
+                interface: SIGNAL_IFACE,
+                member: 'Setup',
+                signature: 'u',
+                args: [this.#interval],
+            });
+            this.#cadence.set(modemPath, 'active');
+        }
+        catch {
+            // A Setup call that errors is a soft gap — surfaced as unsupported, never a
+            // start failure.
+            this.#cadence.set(modemPath, 'unsupported');
+        }
+    }
+}

package/dist/backend/sim-unlock.d.ts

@@ -0,0 +1,13 @@
+import type { SimPukUnlockResult, SimUnlockResult } from '../ports/index.js';
+import type { DbusTransport } from '../transport/index.js';
+/**
+ * Submit a SIM PIN read-before-submit and exactly-once. On a wrong PIN the lock state
+ * is re-read (never resubmitted) to report remaining attempts or a resulting PUK lock.
+ */
+export declare function sendSimPin(transport: DbusTransport, destination: string, modemPath: string, pin: string): Promise<SimUnlockResult>;
+/**
+ * Submit a SIM PUK + new PIN read-before-submit and exactly-once. On a wrong PUK the
+ * remaining PUK attempts are re-read (never resubmitted); zero remaining is a
+ * permanent block.
+ */
+export declare function sendSimPuk(transport: DbusTransport, destination: string, modemPath: string, puk: string, newPin: string): Promise<SimPukUnlockResult>;

package/dist/backend/sim-unlock.js

@@ -0,0 +1,153 @@
+// SIM PIN / PUK unlock — read-before-submit, exactly-once, CeraUI-taxonomy-faithful.
+//
+// The ordering is the whole point (mirrors CeraUI `mmcli.ts` unlockSimPin/Puk): the
+// lock state is READ first, and the secret is submitted EXACTLY ONCE. A blind
+// resubmit walks the SIM toward an irreversible PUK / permanent lockout, so on a
+// failure we only RE-READ the lock state to report remaining attempts — we never
+// resubmit. A PUK cannot be cleared with a PIN, so a PUK-locked SIM is surfaced, not
+// submitted into.
+//
+// The result outcomes map onto A2.2's `SimUnlockResult` / `SimPukUnlockResult`, which
+// mirror CeraUI's own shapes so Phase-B adoption is a rename, not a rewrite:
+//   success → unlocked · wrong-pin → incorrect-pin(+remaining) · puk-required →
+//   sim-puk-required · wrong-puk → incorrect-puk(+remaining) · locked(0) →
+//   permanently-blocked · read failure → error · nothing-to-unlock → unlocked.
+// The secret is passed only as a call arg and is NEVER placed in a `reason` string.
+import { MODEM_IFACE, SIM_IFACE } from './constants.js';
+import { fetchManagedObjects, findInterface, numberProp, propValue, stringProp, } from './managed-objects.js';
+// MMModemLock values we branch on.
+const LOCK_SIM_PIN = 2;
+const LOCK_SIM_PUK = 4;
+const LOCK_SIM_PUK2 = 5;
+function readLockState(tree, modemPath) {
+    const modem = findInterface(tree, modemPath, MODEM_IFACE);
+    if (modem === undefined) {
+        return undefined;
+    }
+    const required = numberProp(modem, 'UnlockRequired') ?? 0;
+    const retries = new Map();
+    const raw = propValue(modem, 'UnlockRetries');
+    if (Array.isArray(raw)) {
+        for (const entry of raw) {
+            if (Array.isArray(entry) && typeof entry[0] === 'number' && typeof entry[1] === 'number') {
+                retries.set(entry[0], entry[1]);
+            }
+        }
+    }
+    return { required, retries };
+}
+/** The object path of a modem's active SIM (its `Sim` property), when present. */
+function activeSimPath(tree, modemPath) {
+    const path = stringProp(findInterface(tree, modemPath, MODEM_IFACE), 'Sim');
+    return path?.startsWith('/') && path !== '/' ? path : undefined;
+}
+const isPukLock = (lock) => lock === LOCK_SIM_PUK || lock === LOCK_SIM_PUK2;
+/**
+ * Submit a SIM PIN read-before-submit and exactly-once. On a wrong PIN the lock state
+ * is re-read (never resubmitted) to report remaining attempts or a resulting PUK lock.
+ */
+export async function sendSimPin(transport, destination, modemPath, pin) {
+    let tree;
+    try {
+        tree = await fetchManagedObjects(transport, destination);
+    }
+    catch {
+        return { outcome: 'error', reason: 'could not read modem lock state before PIN submit' };
+    }
+    const state = readLockState(tree, modemPath);
+    if (state === undefined) {
+        return { outcome: 'error', reason: 'modem not found while reading lock state' };
+    }
+    if (isPukLock(state.required)) {
+        return { outcome: 'sim-puk-required', reason: 'SIM is PUK-locked; a PIN cannot clear it' };
+    }
+    if (state.required !== LOCK_SIM_PIN) {
+        return { outcome: 'unlocked', reason: 'no SIM PIN is pending' };
+    }
+    const simPath = activeSimPath(tree, modemPath);
+    if (simPath === undefined) {
+        return { outcome: 'error', reason: 'no active SIM object to submit the PIN to' };
+    }
+    try {
+        await transport.callMethod({
+            destination,
+            path: simPath,
+            interface: SIM_IFACE,
+            member: 'SendPin',
+            signature: 's',
+            args: [pin],
+        });
+        return { outcome: 'unlocked', reason: 'PIN accepted' };
+    }
+    catch {
+        return classifyPinFailure(transport, destination, modemPath);
+    }
+}
+async function classifyPinFailure(transport, destination, modemPath) {
+    const state = await readLockState(await fetchManagedObjects(transport, destination), modemPath);
+    if (state !== undefined && isPukLock(state.required)) {
+        return { outcome: 'sim-puk-required', reason: 'wrong PIN tripped the SIM into a PUK lock' };
+    }
+    const remaining = state?.retries.get(LOCK_SIM_PIN);
+    return {
+        outcome: 'incorrect-pin',
+        ...(remaining !== undefined ? { remainingAttempts: remaining } : {}),
+        reason: 'PIN was rejected',
+    };
+}
+/**
+ * Submit a SIM PUK + new PIN read-before-submit and exactly-once. On a wrong PUK the
+ * remaining PUK attempts are re-read (never resubmitted); zero remaining is a
+ * permanent block.
+ */
+export async function sendSimPuk(transport, destination, modemPath, puk, newPin) {
+    let tree;
+    try {
+        tree = await fetchManagedObjects(transport, destination);
+    }
+    catch {
+        return { outcome: 'error', reason: 'could not read modem lock state before PUK submit' };
+    }
+    const state = readLockState(tree, modemPath);
+    if (state === undefined) {
+        return { outcome: 'error', reason: 'modem not found while reading lock state' };
+    }
+    if (!isPukLock(state.required)) {
+        return { outcome: 'unlocked', reason: 'no SIM PUK is pending' };
+    }
+    const pukKind = state.required;
+    const simPath = activeSimPath(tree, modemPath);
+    if (simPath === undefined) {
+        return { outcome: 'error', reason: 'no active SIM object to submit the PUK to' };
+    }
+    try {
+        await transport.callMethod({
+            destination,
+            path: simPath,
+            interface: SIM_IFACE,
+            member: 'SendPuk',
+            signature: 'ss',
+            args: [puk, newPin],
+        });
+        return { outcome: 'unlocked', reason: 'PUK accepted; new PIN set' };
+    }
+    catch {
+        return classifyPukFailure(transport, destination, modemPath, pukKind);
+    }
+}
+async function classifyPukFailure(transport, destination, modemPath, pukKind) {
+    const state = await readLockState(await fetchManagedObjects(transport, destination), modemPath);
+    const remaining = state?.retries.get(pukKind);
+    if (remaining === 0) {
+        return {
+            outcome: 'permanently-blocked',
+            remainingAttempts: 0,
+            reason: 'PUK attempts exhausted; SIM is permanently locked',
+        };
+    }
+    return {
+        outcome: 'incorrect-puk',
+        ...(remaining !== undefined ? { remainingAttempts: remaining } : {}),
+        reason: 'PUK was rejected',
+    };
+}