@ceralive/modem-control 0.2.0 → 1.1.0

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',
+    };
+}

package/dist/backend/transition-preconditions.d.ts

@@ -0,0 +1,76 @@
+import type { EpochMillis, IdentityConfidence } from '../domain/index.js';
+import type { ConnectionId, DeviceIfname } from '../ports/index.js';
+import { type CatalogEntry, type CertifiedCatalog, type MmUsbMode, type PermittedTransition, type SkuDiscriminator } from '../usb-mode/index.js';
+import type { InterlockTarget, LifecycleInterlock } from './lifecycle-interlock.js';
+/** A held "transition active" interlock — released when the transaction ends. */
+export interface InterlockHold {
+    release(): Promise<void>;
+}
+/**
+ * The transition interlock. `canDisrupt` (from `LifecycleInterlock`) answers "is it
+ * safe to disrupt this modem now?"; `hold` marks a transition in progress so a
+ * streaming start is blocked for its duration. Both directions, one seam.
+ */
+export interface TransitionInterlock extends LifecycleInterlock {
+    hold(target: InterlockTarget): Promise<InterlockHold>;
+}
+/** The Phase-A interlock: always allows, holds nothing. */
+export declare const ALLOW_ALL_TRANSITION_INTERLOCK: TransitionInterlock;
+/** Live, re-evaluable readiness inputs — re-polled at entry AND in-actor. */
+export interface TransitionReadiness {
+    /** The identity confidence from A3.2's ladder; `'low'` refuses the transition. */
+    readonly identityConfidence: IdentityConfidence;
+}
+/** One USB-mode transition request. */
+export interface UsbModeTransitionRequest {
+    readonly stableKey: string;
+    readonly sku: SkuDiscriminator;
+    readonly fromMode: MmUsbMode;
+    readonly toMode: MmUsbMode;
+    readonly connectionId: ConnectionId;
+    readonly deviceIfname: DeviceIfname;
+    /** Physical-topology UID captured BEFORE the switch — survives re-enumeration. */
+    readonly cachedPhysicalUid: string;
+    /** The MM `Device` UID to inhibit by (cached — the modem disappears mid-switch). */
+    readonly inhibitUid: string;
+    /** Must be `true` (mirrors the CLI `--confirm` flag). */
+    readonly confirm: boolean;
+    /** Must be `true` (an extra maintenance-mode safety gate). */
+    readonly maintenance: boolean;
+    readonly now: EpochMillis;
+    /** Live readiness, re-polled at entry AND in-actor (TOCTOU-safe). */
+    probeReadiness(): Promise<TransitionReadiness>;
+}
+/** How a transition ended. */
+export type UsbModeTransitionOutcome = {
+    readonly status: 'refused';
+    readonly stage: 'entry' | 'in-actor';
+    readonly reason: string;
+    readonly steps: readonly string[];
+} | {
+    readonly status: 'succeeded';
+    readonly newIfname: DeviceIfname;
+    readonly steps: readonly string[];
+} | {
+    readonly status: 'failed';
+    readonly degraded: boolean;
+    readonly reason: string;
+    readonly steps: readonly string[];
+};
+/** The result of a precondition check — the matched entry/transition, or a reason. */
+export type PreconditionResult = {
+    readonly ok: true;
+    readonly entry: CatalogEntry;
+    readonly transition: PermittedTransition;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Check every transition precondition against the LIVE inputs. Called at entry and
+ * again in-actor; a request that passed at entry can fail here if the identity
+ * confidence dropped or the interlock closed in the meantime. Order is cheap-static
+ * checks first (confirm, maintenance, catalog, permitted) then the live probes
+ * (identity, interlock), so a refusal touches as little as possible.
+ */
+export declare function checkTransitionPreconditions(request: UsbModeTransitionRequest, catalog: CertifiedCatalog, interlock: TransitionInterlock): Promise<PreconditionResult>;

package/dist/backend/transition-preconditions.js

@@ -0,0 +1,64 @@
+// USB-mode transition preconditions + the transition interlock seam.
+//
+// The preconditions gate a mode switch and are checked TWICE (draft §rounds 5/6
+// TOCTOU): once at transaction entry (so a doomed request never enters the actor) and
+// again INSIDE the actor (so a request that was valid at entry but became invalid
+// while queued is caught before any disruptive call). `checkTransitionPreconditions`
+// re-polls the LIVE inputs (`probeReadiness`, `interlock.canDisrupt`) each call, so
+// the two checks can genuinely disagree — that disagreement is the TIER-B race.
+//
+// The interlock is BIDIRECTIONAL: `canDisrupt` is the streaming→transition gate (may
+// I disrupt now?), inherited from A3.4's `LifecycleInterlock`; `hold` is the
+// transition→streaming gate (mark "transition active" until released). The Phase-A
+// stub allows both; Phase B wires CeraUI's streaming-admission check into the same
+// interface without changing the transaction.
+import { findCatalogEntry, findPermittedTransition, } from '../usb-mode/index.js';
+const NO_OP_HOLD = {
+    release() {
+        return Promise.resolve();
+    },
+};
+/** The Phase-A interlock: always allows, holds nothing. */
+export const ALLOW_ALL_TRANSITION_INTERLOCK = {
+    canDisrupt() {
+        return Promise.resolve({ allow: true });
+    },
+    hold() {
+        return Promise.resolve(NO_OP_HOLD);
+    },
+};
+/**
+ * Check every transition precondition against the LIVE inputs. Called at entry and
+ * again in-actor; a request that passed at entry can fail here if the identity
+ * confidence dropped or the interlock closed in the meantime. Order is cheap-static
+ * checks first (confirm, maintenance, catalog, permitted) then the live probes
+ * (identity, interlock), so a refusal touches as little as possible.
+ */
+export async function checkTransitionPreconditions(request, catalog, interlock) {
+    if (!request.confirm) {
+        return { ok: false, reason: 'confirm:true is required (missing --confirm)' };
+    }
+    if (!request.maintenance) {
+        return { ok: false, reason: 'maintenance flag is required' };
+    }
+    const entry = findCatalogEntry(catalog, request.sku);
+    if (entry === undefined) {
+        return { ok: false, reason: `uncertified SKU ${request.sku.vidPid} ${request.sku.model}` };
+    }
+    const transition = findPermittedTransition(entry, request.fromMode, request.toMode);
+    if (transition === undefined) {
+        return {
+            ok: false,
+            reason: `transition ${request.fromMode}->${request.toMode} not permitted for ${request.sku.model}`,
+        };
+    }
+    const readiness = await request.probeReadiness();
+    if (readiness.identityConfidence === 'low') {
+        return { ok: false, reason: 'low-confidence identity — refusing to transition' };
+    }
+    const verdict = await interlock.canDisrupt({ stableKey: request.stableKey });
+    if (!verdict.allow) {
+        return { ok: false, reason: `interlock held: ${verdict.reason}` };
+    }
+    return { ok: true, entry, transition };
+}

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

@@ -0,0 +1,39 @@
+import type { IdentityConfidence, LogicalSlotId } from '../../domain/index.js';
+/** The composite baseline key. A change in ANY field is a remap (zero-delta rebase). */
+export interface BaselineKey {
+    readonly logicalSlotId: string;
+    readonly mappingGeneration: number;
+    readonly ifname: string;
+    readonly bootId: string;
+}
+/** Per-slot accounting state. `key`/`lastObserved` are unset before the first sample. */
+export interface SlotAccount {
+    /** Bytes attributed to this slot within the current cycle. */
+    readonly cycleBytes: number;
+    /** UTC start of the cycle `cycleBytes` is accruing into. */
+    readonly cycleStartMs: number;
+    /** True when the last observation was low-confidence and sampling is paused. */
+    readonly paused: boolean;
+    /** The key the baseline was captured under (undefined = no baseline yet). */
+    readonly key?: BaselineKey;
+    /** The cumulative counter value at the last accepted sample. */
+    readonly lastObserved?: number;
+}
+/** One observation fed to the reducer for a single slot in one sampling pass. */
+export interface SampleInput {
+    readonly key: BaselineKey;
+    /** The current cumulative rx+tx counter for the slot's interface. */
+    readonly current: number;
+    readonly confidence: IdentityConfidence;
+    /** The UTC start of the slot's active cycle (from `cycleStart`). */
+    readonly cycleStartMs: number;
+}
+/** A fresh account for a slot first seen in `cycleStartMs`. */
+export declare function initialAccount(cycleStartMs: number): SlotAccount;
+/**
+ * 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`.
+ */
+export declare function applySample(prior: SlotAccount | undefined, input: SampleInput): SlotAccount;
+/** Convenience constructor for a `BaselineKey` from its parts. */
+export declare function baselineKey(logicalSlotId: LogicalSlotId, mappingGeneration: number, ifname: string, bootId: string): BaselineKey;

package/dist/backend/usage/accounting.js

@@ -0,0 +1,73 @@
+// The pure usage-accounting reducer — the heart of the sampler.
+//
+// For each logical slot we keep a per-cycle byte total plus a BASELINE: the last
+// observed cumulative counter value under a specific key. The key is the composite
+// `{logicalSlotId, mappingGeneration, ifname, bootId}`. The rules, all encoded here
+// with zero I/O so they can be exhaustively unit-tested:
+//
+//   - REMAP (any key field changes — e.g. the ifname-to-slot mapping bumped
+//     `mappingGeneration`, or a reboot changed `bootId`): rebaseline with a
+//     ZERO-DELTA sample. We start counting fresh from the current cumulative value
+//     and attribute nothing for that first sample — never a spurious jump.
+//   - SAME-KEY DECREASE (the cumulative counter went DOWN — interface re-created /
+//     counter reset without a reported remap): CLAMP the negative delta to zero and
+//     REBASE the baseline to the new lower value. Never report negative usage.
+//   - LOW CONFIDENCE (ambiguous identity, A3.2 ladder): sampling is PAUSED. We drop
+//     the baseline and attribute nothing; on resume the next sample is zero-delta so
+//     bytes moved during the ambiguous window are never mis-attributed.
+//   - CYCLE ROLLOVER (`now` crossed into a new billing cycle): the per-cycle total
+//     resets to zero. The baseline is kept — the kernel counter is continuous across
+//     a billing boundary; only OUR accounting window resets.
+/** A fresh account for a slot first seen in `cycleStartMs`. */
+export function initialAccount(cycleStartMs) {
+    return { cycleBytes: 0, cycleStartMs, paused: false };
+}
+function sameKey(a, b) {
+    return (a.logicalSlotId === b.logicalSlotId &&
+        a.mappingGeneration === b.mappingGeneration &&
+        a.ifname === b.ifname &&
+        a.bootId === b.bootId);
+}
+/** Apply a cycle rollover: if we crossed into a newer cycle, zero the per-cycle total. */
+function rollCycle(account, cycleStartMs) {
+    if (cycleStartMs > account.cycleStartMs) {
+        return { ...account, cycleBytes: 0, cycleStartMs };
+    }
+    return account;
+}
+/**
+ * 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`.
+ */
+export function applySample(prior, input) {
+    const base = rollCycle(prior ?? initialAccount(input.cycleStartMs), input.cycleStartMs);
+    // Ambiguous identity → pause: attribute nothing and drop the baseline so the
+    // next confident sample re-baselines zero-delta (no back-attribution).
+    if (input.confidence === 'low') {
+        return { cycleBytes: base.cycleBytes, cycleStartMs: base.cycleStartMs, paused: true };
+    }
+    // Remap, first-ever sample, or resuming from a pause → zero-delta rebaseline.
+    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)) {
+        return { ...base, paused: false, key: input.key, lastObserved: input.current };
+    }
+    // Same key: a decrease is a counter reset → clamp the negative delta and rebase.
+    if (input.current < base.lastObserved) {
+        return { ...base, paused: false, key: input.key, lastObserved: input.current };
+    }
+    // Normal case: attribute the non-negative delta and advance the baseline.
+    const delta = input.current - base.lastObserved;
+    return {
+        ...base,
+        paused: false,
+        key: input.key,
+        lastObserved: input.current,
+        cycleBytes: base.cycleBytes + delta,
+    };
+}
+/** Convenience constructor for a `BaselineKey` from its parts. */
+export function baselineKey(logicalSlotId, mappingGeneration, ifname, bootId) {
+    return { logicalSlotId, mappingGeneration, ifname, bootId };
+}

package/dist/backend/usage/billing-cycle.d.ts

@@ -0,0 +1,11 @@
+import type { EpochMillis } from '../../domain/index.js';
+/** Days in a given UTC month. `month` is 0-based (0 = January). Handles leap Feb. */
+export declare function daysInMonth(year: number, month: number): number;
+/** Clamp a requested cycle day to the last valid day of the given month. */
+export declare function clampCycleDay(cycleDay: number, year: number, month: number): number;
+/**
+ * The UTC start (`EpochMillis`) of the cycle that `now` falls in for a given
+ * `cycleDay`. If `now` is before this month's (clamped) boundary the active cycle
+ * began on the previous month's boundary; otherwise it began on this month's.
+ */
+export declare function cycleStart(now: EpochMillis, cycleDay: number): EpochMillis;

package/dist/backend/usage/billing-cycle.js

@@ -0,0 +1,39 @@
+// UTC billing-cycle computation with month-length clamping.
+//
+// A usage cycle resets on a configured day of the month (`cycleDay`, 1–31) in UTC.
+// Months are not all the same length, so a `cycleDay` past the end of a short month
+// must clamp to that month's LAST day rather than rolling into the next month or
+// throwing: `cycleDay: 31` resolves to Feb 28 (or Feb 29 in a leap year), Apr 30,
+// etc. All arithmetic is UTC — the device clock's local zone never shifts a cycle.
+/** Days in a given UTC month. `month` is 0-based (0 = January). Handles leap Feb. */
+export function daysInMonth(year, month) {
+    // Day 0 of the next month is the last day of this month; UTC avoids DST drift.
+    return new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+}
+/** Clamp a requested cycle day to the last valid day of the given month. */
+export function clampCycleDay(cycleDay, year, month) {
+    const floor = Math.max(1, Math.trunc(cycleDay));
+    return Math.min(floor, daysInMonth(year, month));
+}
+/** The UTC epoch-ms of the cycle boundary in a specific month (clamped). */
+function boundaryFor(cycleDay, year, month) {
+    return Date.UTC(year, month, clampCycleDay(cycleDay, year, month));
+}
+/**
+ * The UTC start (`EpochMillis`) of the cycle that `now` falls in for a given
+ * `cycleDay`. If `now` is before this month's (clamped) boundary the active cycle
+ * began on the previous month's boundary; otherwise it began on this month's.
+ */
+export function cycleStart(now, cycleDay) {
+    const at = new Date(now);
+    const year = at.getUTCFullYear();
+    const month = at.getUTCMonth();
+    const thisBoundary = boundaryFor(cycleDay, year, month);
+    if (now >= thisBoundary) {
+        return thisBoundary;
+    }
+    // Roll back one month (December wraps to the prior year), re-clamping there.
+    const prevMonth = month === 0 ? 11 : month - 1;
+    const prevYear = month === 0 ? year - 1 : year;
+    return boundaryFor(cycleDay, prevYear, prevMonth);
+}

package/dist/backend/usage/boot-id.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Read the current kernel boot id (a UUID string). The path is injectable for tests;
+ * the default is the live `/proc` file. A read failure yields an empty string so the
+ * sampler still starts (baselines then simply never match a persisted session).
+ */
+export declare function readBootId(path?: string): Promise<string>;

package/{src/backend/usage/boot-id.ts → dist/backend/usage/boot-id.js}

@@ -3,16 +3,16 @@
 // `/proc/sys/kernel/random/boot_id` is a per-boot random UUID string. It changes on
 // every reboot, which is exactly when interface byte counters reset to zero, so the
 // sampler keys its baselines on it and re-baselines when it changes.
-
 /**
  * Read the current kernel boot id (a UUID string). The path is injectable for tests;
  * the default is the live `/proc` file. A read failure yields an empty string so the
  * sampler still starts (baselines then simply never match a persisted session).
  */
-export async function readBootId(path = '/proc/sys/kernel/random/boot_id'): Promise<string> {
-	try {
-		return (await Bun.file(path).text()).trim();
-	} catch {
-		return '';
-	}
+export async function readBootId(path = '/proc/sys/kernel/random/boot_id') {
+    try {
+        return (await Bun.file(path).text()).trim();
+    }
+    catch {
+        return '';
+    }
 }

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

@@ -0,0 +1,8 @@
+export { applySample, type BaselineKey, baselineKey, initialAccount, type SampleInput, type SlotAccount, } from './accounting.js';
+export { clampCycleDay, cycleStart, daysInMonth } from './billing-cycle.js';
+export { readBootId } from './boot-id.js';
+export { createUsagePolicyFileStore, isValidCycleDay, isValidThresholdBytes, type PersistedUsagePolicy, type PersistedUsagePolicySlot, selectUsagePolicy, USAGE_POLICY_SCHEMA_VERSION, type UsagePolicyFileStoreOptions, type UsagePolicyLogEvent, type UsagePolicyLogger, type UsagePolicyStore, } from './policy-store.js';
+export { getUsagePolicy, type SetUsagePolicyDeps, type SetUsagePolicyRejection, type SetUsagePolicyRequest, type SetUsagePolicyResult, setUsagePolicy, type UsagePolicyApplication, type UsagePolicyTarget, } from './policy-write.js';
+export { type CounterSource, parseProcNetDev, procNetDevCounterSource, } from './proc-net-dev.js';
+export { createUsageSampler, type SlotUsageSnapshot, type UsageObservation, UsageSampler, type UsageSamplerOptions, type UsageSnapshot, } from './sampler.js';
+export { createUsageFileStore, type PersistedSlot, type PersistedUsage, USAGE_SCHEMA_VERSION, type UsageFileStoreOptions, type UsageLogEvent, type UsageLogger, type UsageStore, } from './store.js';

package/dist/backend/usage/index.js

@@ -0,0 +1,11 @@
+// Data-usage sampler — internal all-interface sampler over `/proc/net/dev`
+// CUMULATIVE counters (A4.3). Public surface consumed by the A6.1 bench CLI `usage`
+// command (via `UsageSnapshot`) and the composition root that wires the sampler.
+export { applySample, baselineKey, initialAccount, } from './accounting.js';
+export { clampCycleDay, cycleStart, daysInMonth } from './billing-cycle.js';
+export { readBootId } from './boot-id.js';
+export { createUsagePolicyFileStore, isValidCycleDay, isValidThresholdBytes, selectUsagePolicy, USAGE_POLICY_SCHEMA_VERSION, } from './policy-store.js';
+export { getUsagePolicy, setUsagePolicy, } from './policy-write.js';
+export { parseProcNetDev, procNetDevCounterSource, } from './proc-net-dev.js';
+export { createUsageSampler, UsageSampler, } from './sampler.js';
+export { createUsageFileStore, USAGE_SCHEMA_VERSION, } from './store.js';