@ceralive/modem-control 1.2.1 → 1.4.0

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

@@ -2,15 +2,32 @@ 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. */
+/**
+ * MM's default reporting rate is seconds; callers pass whole seconds.
+ *
+ * It is a DEFAULT and not a constant: extended signal costs a modem-side poll per tick,
+ * so an embedding process running a bonded uplink may want it faster than a bench tool
+ * does. The rate is therefore injectable end to end — `SignalSetupManagerOptions`,
+ * `MmDbusBackendOptions.signalIntervalSeconds` and
+ * `ModemManagerProviderOptions.signalIntervalSeconds` are the same seam at three levels
+ * — and this value is what an absent injection resolves to, at every one of them.
+ */
 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`. */
+    /**
+     * Reporting interval in seconds passed to `Signal.Setup`.
+     *
+     * `Setup` takes a `u`, so a fractional or negative rate has no wire representation
+     * and is refused HERE rather than marshalled into whatever the codec makes of it —
+     * a modem silently polling at the wrong cadence is a defect nothing downstream can
+     * see. An absent value is not a refusal; it takes the default.
+     */
     readonly intervalSeconds?: number;
 }
+export declare function resolveSignalInterval(intervalSeconds: number | undefined): 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
@@ -19,6 +36,8 @@ export interface SignalSetupManagerOptions {
 export declare class SignalSetupManager {
     #private;
     constructor(options: SignalSetupManagerOptions);
+    /** The rate every `Signal.Setup` on this manager carries — injected, or the default. */
+    get intervalSeconds(): number;
     /** The last-known cadence for a modem path (`'unknown'` until first applied). */
     cadenceFor(modemPath: string): SignalCadence;
     /**

package/dist/backend/signal-setup.js

@@ -19,8 +19,26 @@ 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. */
+/**
+ * MM's default reporting rate is seconds; callers pass whole seconds.
+ *
+ * It is a DEFAULT and not a constant: extended signal costs a modem-side poll per tick,
+ * so an embedding process running a bonded uplink may want it faster than a bench tool
+ * does. The rate is therefore injectable end to end — `SignalSetupManagerOptions`,
+ * `MmDbusBackendOptions.signalIntervalSeconds` and
+ * `ModemManagerProviderOptions.signalIntervalSeconds` are the same seam at three levels
+ * — and this value is what an absent injection resolves to, at every one of them.
+ */
 export const DEFAULT_SIGNAL_INTERVAL_SECONDS = 5;
+export function resolveSignalInterval(intervalSeconds) {
+    if (intervalSeconds === undefined) {
+        return DEFAULT_SIGNAL_INTERVAL_SECONDS;
+    }
+    if (!Number.isInteger(intervalSeconds) || intervalSeconds <= 0) {
+        throw new RangeError(`Signal.Setup interval must be a positive whole number of seconds, got ${intervalSeconds}`);
+    }
+    return intervalSeconds;
+}
 /**
  * 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
@@ -37,7 +55,11 @@ export class SignalSetupManager {
     constructor(options) {
         this.#transport = options.transport;
         this.#destination = options.destination ?? MM_BUS_NAME;
-        this.#interval = options.intervalSeconds ?? DEFAULT_SIGNAL_INTERVAL_SECONDS;
+        this.#interval = resolveSignalInterval(options.intervalSeconds);
+    }
+    /** The rate every `Signal.Setup` on this manager carries — injected, or the default. */
+    get intervalSeconds() {
+        return this.#interval;
     }
     /** The last-known cadence for a modem path (`'unknown'` until first applied). */
     cadenceFor(modemPath) {

package/dist/backend/usage/accounting.d.ts

@@ -30,6 +30,13 @@ export interface SampleInput {
 }
 /** A fresh account for a slot first seen in `cycleStartMs`. */
 export declare function initialAccount(cycleStartMs: number): SlotAccount;
+/**
+ * Whether two baseline keys name the SAME counter — a difference in any field is a
+ * remap. Exported because `sampling.ts` must ask the identical question before it
+ * divides a delta by an interval; two spellings of it would eventually disagree, and
+ * the rate is the half that would then be wrong silently.
+ */
+export declare function sameBaselineKey(a: BaselineKey, b: BaselineKey): boolean;
 /**
  * Fold one observation into a slot's account, returning the NEXT account. Pure —
  * no clock, no I/O; the caller supplies `current`, `confidence` and `cycleStartMs`.

package/dist/backend/usage/accounting.js

@@ -22,7 +22,13 @@
 export function initialAccount(cycleStartMs) {
     return { cycleBytes: 0, cycleStartMs, paused: false };
 }
-function sameKey(a, b) {
+/**
+ * Whether two baseline keys name the SAME counter — a difference in any field is a
+ * remap. Exported because `sampling.ts` must ask the identical question before it
+ * divides a delta by an interval; two spellings of it would eventually disagree, and
+ * the rate is the half that would then be wrong silently.
+ */
+export function sameBaselineKey(a, b) {
     return (a.logicalSlotId === b.logicalSlotId &&
         a.mappingGeneration === b.mappingGeneration &&
         a.ifname === b.ifname &&
@@ -50,7 +56,7 @@ export function applySample(prior, input) {
     if (base.paused || base.key === undefined || base.lastObserved === undefined) {
         return { ...base, paused: false, key: input.key, lastObserved: input.current };
     }
-    if (!sameKey(base.key, input.key)) {
+    if (!sameBaselineKey(base.key, input.key)) {
         return { ...base, paused: false, key: input.key, lastObserved: input.current };
     }
     // Same key: a decrease is a counter reset → clamp the negative delta and rebase.

package/dist/backend/usage/persistence.d.ts

@@ -0,0 +1,4 @@
+import type { SlotAccount } from './accounting.js';
+import type { PersistedUsage } from './store.js';
+export declare function hydrateUsageAccounts(initial: PersistedUsage, bootId: string): Map<string, SlotAccount>;
+export declare function persistedUsageState(bootId: string, savedAtMs: number, accounts: ReadonlyMap<string, SlotAccount>): PersistedUsage;

package/dist/backend/usage/persistence.js

@@ -0,0 +1,59 @@
+// The persisted usage document — what survives a restart, and what deliberately does not.
+//
+// THROUGHPUT IS NOT PERSISTED, and its absence from `PersistedSlot` is a decision
+// rather than an omission. A rate is a measurement over an interval whose two ends this
+// process observed; a restart observed neither. Writing the last rate down would
+// republish a figure measured before the gap as though it described now, and writing
+// the baseline's sample TIME down would invite the next sample to divide a whole
+// downtime's bytes by one sampling interval — the same invented spike `sampling.ts`
+// refuses for a missing interface. So the counter BASELINE resumes across a same-boot
+// reload (that is a cumulative total, and it is still true) while the rate restarts
+// unmeasured. `persistence.test.ts` pins the negative.
+import { USAGE_SCHEMA_VERSION } from './store.js';
+export function hydrateUsageAccounts(initial, bootId) {
+    const accounts = new Map();
+    const sameBoot = initial.bootId === bootId;
+    for (const slot of initial.slots) {
+        const canResume = sameBoot &&
+            slot.ifname !== undefined &&
+            slot.mappingGeneration !== undefined &&
+            slot.lastObserved !== undefined;
+        if (canResume) {
+            accounts.set(slot.logicalSlotId, {
+                cycleBytes: slot.cycleBytes,
+                cycleStartMs: slot.cycleStartMs,
+                paused: false,
+                key: {
+                    logicalSlotId: slot.logicalSlotId,
+                    mappingGeneration: slot.mappingGeneration,
+                    ifname: slot.ifname,
+                    bootId,
+                },
+                lastObserved: slot.lastObserved,
+            });
+        }
+        else {
+            accounts.set(slot.logicalSlotId, {
+                cycleBytes: slot.cycleBytes,
+                cycleStartMs: slot.cycleStartMs,
+                paused: false,
+            });
+        }
+    }
+    return accounts;
+}
+export function persistedUsageState(bootId, savedAtMs, accounts) {
+    const slots = [];
+    for (const [logicalSlotId, account] of accounts) {
+        slots.push({
+            logicalSlotId,
+            cycleBytes: account.cycleBytes,
+            cycleStartMs: account.cycleStartMs,
+            ...(account.key !== undefined
+                ? { mappingGeneration: account.key.mappingGeneration, ifname: account.key.ifname }
+                : {}),
+            ...(account.lastObserved !== undefined ? { lastObserved: account.lastObserved } : {}),
+        });
+    }
+    return { schemaVersion: USAGE_SCHEMA_VERSION, bootId, savedAtMs, slots };
+}

package/dist/backend/usage/policy.d.ts

@@ -0,0 +1,24 @@
+import type { DesiredUsage } from '../../domain/index.js';
+import type { SlotAccount } from './accounting.js';
+import type { UsageSnapshot } from './sampler.js';
+import type { SlotRate } from './sampling.js';
+export interface UsagePolicyState {
+    readonly bootId: string;
+    readonly defaultCycleDay: number;
+    readonly accounts: Map<string, SlotAccount>;
+    readonly policies: Map<string, DesiredUsage>;
+    readonly policyOverrides: Map<string, DesiredUsage>;
+}
+export interface UsagePolicyApplicationResult {
+    readonly cycleStartMs: number;
+    readonly cycleReset: boolean;
+    readonly dirty: boolean;
+}
+export declare function applyPolicy(state: UsagePolicyState, logicalSlotId: string, usage: DesiredUsage, now: number): UsagePolicyApplicationResult;
+export interface UsageProjectionState {
+    readonly bootId: string;
+    readonly accounts: ReadonlyMap<string, SlotAccount>;
+    readonly policies: ReadonlyMap<string, DesiredUsage>;
+    readonly rates: ReadonlyMap<string, SlotRate>;
+}
+export declare function projectUsageSnapshot(state: UsageProjectionState, generatedAtMs: number): UsageSnapshot;

package/dist/backend/usage/policy.js

@@ -0,0 +1,38 @@
+import { epochMillis } from '../../domain/index.js';
+import { initialAccount } from './accounting.js';
+import { cycleStart } from './billing-cycle.js';
+export function applyPolicy(state, logicalSlotId, usage, now) {
+    state.policyOverrides.set(logicalSlotId, usage);
+    state.policies.set(logicalSlotId, usage);
+    const cycleStartMs = cycleStart(epochMillis(now), usage.cycleDay ?? state.defaultCycleDay);
+    const account = state.accounts.get(logicalSlotId);
+    if (account === undefined) {
+        state.accounts.set(logicalSlotId, initialAccount(cycleStartMs));
+        return { cycleStartMs, cycleReset: false, dirty: true };
+    }
+    if (account.cycleStartMs === cycleStartMs) {
+        return { cycleStartMs, cycleReset: false, dirty: false };
+    }
+    state.accounts.set(logicalSlotId, { ...account, cycleBytes: 0, cycleStartMs });
+    return { cycleStartMs, cycleReset: true, dirty: true };
+}
+export function projectUsageSnapshot(state, generatedAtMs) {
+    const slots = [];
+    for (const [slotId, account] of state.accounts) {
+        const policy = state.policies.get(slotId);
+        const thresholdBytes = policy?.thresholdBytes;
+        // An unmeasured interval OMITS the key rather than reporting 0 — see `SlotRate`.
+        const bytesPerSecond = state.rates.get(slotId)?.bytesPerSecond;
+        slots.push({
+            logicalSlotId: slotId,
+            cycleBytes: account.cycleBytes,
+            cycleStartMs: account.cycleStartMs,
+            paused: account.paused,
+            ...(policy?.cycleDay !== undefined ? { cycleDay: policy.cycleDay } : {}),
+            ...(thresholdBytes !== undefined ? { thresholdBytes } : {}),
+            thresholdExceeded: thresholdBytes !== undefined && account.cycleBytes > thresholdBytes,
+            ...(bytesPerSecond !== undefined ? { rateBytesPerSecond: bytesPerSecond } : {}),
+        });
+    }
+    return { bootId: state.bootId, generatedAtMs, slots };
+}

package/dist/backend/usage/sampler.d.ts

@@ -1,4 +1,4 @@
-import { type DesiredUsage, type LogicalSlotId } from '../../domain/index.js';
+import type { DesiredUsage, LogicalSlotId } from '../../domain/index.js';
 import type { CounterSource } from './proc-net-dev.js';
 import type { UsageStore } from './store.js';
 /** One slot's observation for a sampling pass — identity + mapping + local policy. */
@@ -23,6 +23,12 @@ export interface SlotUsageSnapshot {
     readonly thresholdBytes?: number;
     /** Advisory-only: `cycleBytes > thresholdBytes`. Never gates the connection. */
     readonly thresholdExceeded: boolean;
+    /**
+     * Throughput over the last measured sampling interval. ABSENT — never 0 — when
+     * this pass had no interval to measure: a first sample, a rebaseline, a paused
+     * slot, a missing interface, or a counter that went BACKWARDS. See `SlotRate`.
+     */
+    readonly rateBytesPerSecond?: number;
 }
 /** The sampler's current state, per slot, at a point in time. */
 export interface UsageSnapshot {

package/dist/backend/usage/sampler.js

@@ -10,23 +10,11 @@
 // `flush()` shutdown hook. A crash therefore loses AT MOST ~1 minute of unpersisted
 // deltas (the window since the last rate-limited write); a clean shutdown calls
 // `flush()` and loses effectively nothing.
-import { epochMillis } from '../../domain/index.js';
-import { applySample, initialAccount } from './accounting.js';
-import { cycleStart } from './billing-cycle.js';
-import { USAGE_SCHEMA_VERSION } from './store.js';
+import { hydrateUsageAccounts, persistedUsageState } from './persistence.js';
+import { applyPolicy, projectUsageSnapshot } from './policy.js';
+import { applyUsageSamples } from './sampling.js';
 const DEFAULT_PERSIST_INTERVAL_MS = 60_000;
 const DEFAULT_CYCLE_DAY = 1;
-function toPersistedSlot(logicalSlotId, account) {
-    return {
-        logicalSlotId,
-        cycleBytes: account.cycleBytes,
-        cycleStartMs: account.cycleStartMs,
-        ...(account.key !== undefined
-            ? { mappingGeneration: account.key.mappingGeneration, ifname: account.key.ifname }
-            : {}),
-        ...(account.lastObserved !== undefined ? { lastObserved: account.lastObserved } : {}),
-    };
-}
 export class UsageSampler {
     #bootId;
     #source;
@@ -34,7 +22,7 @@ export class UsageSampler {
     #now;
     #persistIntervalMs;
     #defaultCycleDay;
-    #accounts = new Map();
+    #accounts;
     #policies = new Map();
     // Policies written through `applyUsagePolicy` OUTRANK whatever an observation
     // carries, for the life of the process. Without this, the next `sample()` would
@@ -43,6 +31,10 @@ export class UsageSampler {
     // revert. The durable store is the source of truth for both, so an override and
     // an observation can only ever disagree inside that window.
     #policyOverrides = new Map();
+    // Rates are IN-MEMORY ONLY and start empty on every construction — deliberately,
+    // see `persistence.ts`. A throughput is a measurement over an interval this
+    // process observed both ends of; a restart has observed neither.
+    #rates = new Map();
     #lastPersistMs;
     #dirty = false;
     constructor(options, initial) {
@@ -53,7 +45,7 @@ export class UsageSampler {
         this.#persistIntervalMs = options.persistIntervalMs ?? DEFAULT_PERSIST_INTERVAL_MS;
         this.#defaultCycleDay = options.defaultCycleDay ?? DEFAULT_CYCLE_DAY;
         this.#lastPersistMs = this.#now();
-        this.#hydrate(initial);
+        this.#accounts = hydrateUsageAccounts(initial, this.#bootId);
     }
     /** Load persisted state (recreating a fresh file if absent/corrupt) then build the sampler. */
     static async create(options) {
@@ -61,91 +53,29 @@ export class UsageSampler {
         const initial = await options.store.load(options.bootId, now());
         return new UsageSampler(options, initial);
     }
-    /** Rebuild in-memory accounts. A reboot (differing boot id) drops the baselines. */
-    #hydrate(initial) {
-        const sameBoot = initial.bootId === this.#bootId;
-        for (const slot of initial.slots) {
-            const canResume = sameBoot &&
-                slot.ifname !== undefined &&
-                slot.mappingGeneration !== undefined &&
-                slot.lastObserved !== undefined;
-            if (canResume) {
-                const key = {
-                    logicalSlotId: slot.logicalSlotId,
-                    mappingGeneration: slot.mappingGeneration,
-                    ifname: slot.ifname,
-                    bootId: this.#bootId,
-                };
-                this.#accounts.set(slot.logicalSlotId, {
-                    cycleBytes: slot.cycleBytes,
-                    cycleStartMs: slot.cycleStartMs,
-                    paused: false,
-                    key,
-                    lastObserved: slot.lastObserved,
-                });
-            }
-            else {
-                this.#accounts.set(slot.logicalSlotId, {
-                    cycleBytes: slot.cycleBytes,
-                    cycleStartMs: slot.cycleStartMs,
-                    paused: false,
-                });
-            }
-        }
-    }
     /** Take one sampling pass over the current counters for the given observations. */
     async sample(observations) {
         const counters = await this.#source.read();
         const now = this.#now();
-        for (const obs of observations) {
-            const slotId = obs.logicalSlotId;
-            const usage = this.#policyOverrides.get(slotId) ?? obs.usage;
-            this.#policies.set(slotId, usage);
-            const cycleDay = usage.cycleDay ?? this.#defaultCycleDay;
-            const cycleStartMs = cycleStart(epochMillis(now), cycleDay);
-            const current = counters.get(obs.ifname);
-            if (current === undefined) {
-                // No reading for this interface — ensure the slot exists, attribute nothing.
-                if (!this.#accounts.has(slotId)) {
-                    this.#accounts.set(slotId, initialAccount(cycleStartMs));
-                }
-                continue;
-            }
-            const key = {
-                logicalSlotId: slotId,
-                mappingGeneration: obs.mappingGeneration,
-                ifname: obs.ifname,
-                bootId: this.#bootId,
-            };
-            const next = applySample(this.#accounts.get(slotId), {
-                key,
-                current,
-                confidence: obs.confidence,
-                cycleStartMs,
-            });
-            this.#accounts.set(slotId, next);
-        }
+        applyUsageSamples({
+            bootId: this.#bootId,
+            defaultCycleDay: this.#defaultCycleDay,
+            accounts: this.#accounts,
+            policies: this.#policies,
+            policyOverrides: this.#policyOverrides,
+            rates: this.#rates,
+        }, observations, counters, now);
         this.#dirty = true;
         await this.#maybePersist(now);
     }
     /** Current per-slot usage — the queryable snapshot the CLI and platform read. */
     snapshot() {
-        const generatedAtMs = this.#now();
-        const slots = [];
-        for (const [slotId, account] of this.#accounts) {
-            const policy = this.#policies.get(slotId);
-            const thresholdBytes = policy?.thresholdBytes;
-            slots.push({
-                logicalSlotId: slotId,
-                cycleBytes: account.cycleBytes,
-                cycleStartMs: account.cycleStartMs,
-                paused: account.paused,
-                ...(policy?.cycleDay !== undefined ? { cycleDay: policy.cycleDay } : {}),
-                ...(thresholdBytes !== undefined ? { thresholdBytes } : {}),
-                thresholdExceeded: thresholdBytes !== undefined && account.cycleBytes > thresholdBytes,
-            });
-        }
-        return { bootId: this.#bootId, generatedAtMs, slots };
+        return projectUsageSnapshot({
+            bootId: this.#bootId,
+            accounts: this.#accounts,
+            policies: this.#policies,
+            rates: this.#rates,
+        }, this.#now());
     }
     /**
      * Apply an operator's usage policy to this slot immediately, without waiting
@@ -161,22 +91,15 @@ export class UsageSampler {
      * moves no anchor and therefore resets nothing.
      */
     applyUsagePolicy(logicalSlotId, usage, atMs) {
-        const now = atMs ?? this.#now();
-        this.#policyOverrides.set(logicalSlotId, usage);
-        this.#policies.set(logicalSlotId, usage);
-        const cycleStartMs = cycleStart(epochMillis(now), usage.cycleDay ?? this.#defaultCycleDay);
-        const account = this.#accounts.get(logicalSlotId);
-        if (account === undefined) {
-            this.#accounts.set(logicalSlotId, initialAccount(cycleStartMs));
-            this.#dirty = true;
-            return { cycleStartMs, cycleReset: false };
-        }
-        if (account.cycleStartMs === cycleStartMs) {
-            return { cycleStartMs, cycleReset: false };
-        }
-        this.#accounts.set(logicalSlotId, { ...account, cycleBytes: 0, cycleStartMs });
-        this.#dirty = true;
-        return { cycleStartMs, cycleReset: true };
+        const result = applyPolicy({
+            bootId: this.#bootId,
+            defaultCycleDay: this.#defaultCycleDay,
+            accounts: this.#accounts,
+            policies: this.#policies,
+            policyOverrides: this.#policyOverrides,
+        }, logicalSlotId, usage, atMs ?? this.#now());
+        this.#dirty ||= result.dirty;
+        return { cycleStartMs: result.cycleStartMs, cycleReset: result.cycleReset };
     }
     /** Flush unpersisted state immediately — the shutdown hook (bounds loss to ≤1 min). */
     async flush() {
@@ -190,16 +113,7 @@ export class UsageSampler {
         }
     }
     async #persist(now) {
-        const slots = [];
-        for (const [slotId, account] of this.#accounts) {
-            slots.push(toPersistedSlot(slotId, account));
-        }
-        const state = {
-            schemaVersion: USAGE_SCHEMA_VERSION,
-            bootId: this.#bootId,
-            savedAtMs: now,
-            slots,
-        };
+        const state = persistedUsageState(this.#bootId, now, this.#accounts);
         await this.#store.save(state);
         this.#lastPersistMs = now;
         this.#dirty = false;

package/dist/backend/usage/sampling.d.ts

@@ -0,0 +1,38 @@
+import type { DesiredUsage } from '../../domain/index.js';
+import { type SlotAccount } from './accounting.js';
+import type { UsageObservation } from './sampler.js';
+/**
+ * One slot's throughput measurement.
+ *
+ * `sampledAtMs` is when the counter behind the current baseline was read; without it
+ * there is no interval to divide a delta by. `bytesPerSecond` is ABSENT — never zero —
+ * whenever this pass had no measurable interval, and that is a frequent, real answer:
+ * the first sample, a rebaseline, a paused slot, an interface missing from the counter
+ * table, and a counter that went BACKWARDS each produce one.
+ *
+ * The backwards case is the one worth spelling out. `/proc/net/dev` counters are
+ * per-interface and cumulative, and they restart at zero when the interface is
+ * re-created — a modem replug, a `wwan0` teardown, a driver reload. Subtracting across
+ * that boundary yields a negative number, and both obvious repairs report something
+ * untrue: clamping to zero shows an idle link that was in fact carrying traffic, while
+ * taking the raw post-reset value shows every byte since the interface came up as if it
+ * had all moved inside one sampling interval. Reporting NOTHING is the honest answer,
+ * and `applySample` rebases the baseline in the same pass so the NEXT interval measures
+ * correctly rather than inheriting the gap.
+ *
+ * Idea provenance: `irlserver/modem-metrics` (MIT) — concepts adopted, no source code
+ * copied. See `docs/adr/ADR-STAY-TYPESCRIPT.md`.
+ */
+export interface SlotRate {
+    readonly sampledAtMs: number;
+    readonly bytesPerSecond?: number;
+}
+export interface UsageSamplingState {
+    readonly bootId: string;
+    readonly defaultCycleDay: number;
+    readonly accounts: Map<string, SlotAccount>;
+    readonly policies: Map<string, DesiredUsage>;
+    readonly policyOverrides: ReadonlyMap<string, DesiredUsage>;
+    readonly rates: Map<string, SlotRate>;
+}
+export declare function applyUsageSamples(state: UsageSamplingState, observations: readonly UsageObservation[], counters: ReadonlyMap<string, number>, now: number): void;

package/dist/backend/usage/sampling.js

@@ -0,0 +1,72 @@
+import { epochMillis } from '../../domain/index.js';
+import { applySample, initialAccount, sameBaselineKey, } from './accounting.js';
+import { cycleStart } from './billing-cycle.js';
+/**
+ * Measure one interval, or state that there was none. Pure — the caller supplies the
+ * prior account, the prior rate sample and `now`. Every early return is a case where a
+ * number could be produced but would not be a measurement; see `SlotRate`.
+ */
+function measureRate(prior, priorRate, input, now) {
+    const unmeasured = { sampledAtMs: now };
+    if (input.confidence === 'low') {
+        return unmeasured;
+    }
+    if (prior === undefined ||
+        prior.paused ||
+        prior.key === undefined ||
+        prior.lastObserved === undefined) {
+        return unmeasured;
+    }
+    if (!sameBaselineKey(prior.key, input.key)) {
+        return unmeasured;
+    }
+    // No prior rate sample means no interval was ever measured under this baseline —
+    // it was restored from disk, or the interface was absent from the last pass. The
+    // elapsed wall time is then a gap, not a sampling interval.
+    if (priorRate === undefined) {
+        return unmeasured;
+    }
+    if (input.current < prior.lastObserved) {
+        return unmeasured;
+    }
+    const elapsedMs = now - priorRate.sampledAtMs;
+    if (elapsedMs <= 0) {
+        return unmeasured;
+    }
+    return {
+        sampledAtMs: now,
+        bytesPerSecond: ((input.current - prior.lastObserved) * 1000) / elapsedMs,
+    };
+}
+export function applyUsageSamples(state, observations, counters, now) {
+    for (const observation of observations) {
+        const slotId = observation.logicalSlotId;
+        const usage = state.policyOverrides.get(slotId) ?? observation.usage;
+        state.policies.set(slotId, usage);
+        const cycleDay = usage.cycleDay ?? state.defaultCycleDay;
+        const cycleStartMs = cycleStart(epochMillis(now), cycleDay);
+        const current = counters.get(observation.ifname);
+        if (current === undefined) {
+            if (!state.accounts.has(slotId)) {
+                state.accounts.set(slotId, initialAccount(cycleStartMs));
+            }
+            // The counter was not readable this pass. Dropping the rate sample costs
+            // the NEXT pass its rate too, which is the point: whatever moved while the
+            // interface was missing did not move inside one sampling interval, and
+            // dividing it by one would render an invented spike.
+            state.rates.delete(slotId);
+            continue;
+        }
+        const key = {
+            logicalSlotId: slotId,
+            mappingGeneration: observation.mappingGeneration,
+            ifname: observation.ifname,
+            bootId: state.bootId,
+        };
+        const prior = state.accounts.get(slotId);
+        const rateInput = { key, current, confidence: observation.confidence };
+        state.rates.set(slotId, measureRate(prior, state.rates.get(slotId), rateInput, now));
+        const next = applySample(prior, { ...rateInput, cycleStartMs });
+        state.accounts.set(slotId, next);
+    }
+}

package/dist/backend/usb-mode-transition/admission.d.ts

@@ -0,0 +1,5 @@
+import type { InhibitLease, ModemManagerPort } from '../../ports/index.js';
+import type { CertifiedCatalog } from '../../usb-mode/index.js';
+import { type TransitionInterlock, type UsbModeTransitionRequest } from '../transition-preconditions.js';
+export declare function checkTransitionAdmission(request: UsbModeTransitionRequest, catalog: CertifiedCatalog, interlock: TransitionInterlock): Promise<import("..").PreconditionResult>;
+export declare function releaseInhibit(modemManager: Pick<ModemManagerPort, 'uninhibit'>, lease: InhibitLease | undefined, steps: string[]): Promise<undefined>;

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

@@ -0,0 +1,12 @@
+import { checkTransitionPreconditions, } from '../transition-preconditions.js';
+export function checkTransitionAdmission(request, catalog, interlock) {
+    return checkTransitionPreconditions(request, catalog, interlock);
+}
+export async function releaseInhibit(modemManager, lease, steps) {
+    if (lease === undefined) {
+        return undefined;
+    }
+    steps.push('force-uninhibit');
+    await modemManager.uninhibit(lease).catch(() => undefined);
+    return undefined;
+}

package/dist/backend/usb-mode-transition/at.d.ts

@@ -0,0 +1,13 @@
+import type { InhibitLease, ModemManagerPort } from '../../ports/index.js';
+import { type AtAuditSink, AtCommandLease, type AtCommandSender } from '../at-lease.js';
+export interface TransitionAtLeaseOptions {
+    readonly sender: AtCommandSender;
+    readonly allowlistedCommands: readonly string[];
+    readonly timeoutMs: number;
+    readonly modemManager: Pick<ModemManagerPort, 'uninhibit'>;
+    readonly currentInhibit: () => InhibitLease | undefined;
+    readonly clearInhibit: () => void;
+    readonly steps: string[];
+    readonly audit?: AtAuditSink;
+}
+export declare function createTransitionAtLease(options: TransitionAtLeaseOptions): AtCommandLease;

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

@@ -0,0 +1,15 @@
+import { AtCommandLease, computeAtAllowlist, } from '../at-lease.js';
+import { releaseInhibit } from './admission.js';
+export function createTransitionAtLease(options) {
+    return new AtCommandLease({
+        sender: options.sender,
+        allowlist: computeAtAllowlist(options.allowlistedCommands),
+        timeoutMs: options.timeoutMs,
+        onWatchdog: async () => {
+            const held = options.currentInhibit();
+            options.clearInhibit();
+            await releaseInhibit(options.modemManager, held, options.steps);
+        },
+        ...(options.audit !== undefined ? { audit: options.audit } : {}),
+    });
+}

package/dist/backend/usb-mode-transition/outcome.d.ts

@@ -0,0 +1,4 @@
+import type { AtCommandLease } from '../at-lease.js';
+import { type UsbDeviceSnapshot } from '../device-classifier.js';
+import type { UsbModeTransitionPlan } from '../transition-preconditions.js';
+export declare function transitionPostconditionFailure(plan: UsbModeTransitionPlan, device: UsbDeviceSnapshot, lease: AtCommandLease, inhibitUid: string, steps: string[]): Promise<string | undefined>;