@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/backend/usage/policy-store.js

@@ -0,0 +1,161 @@
+// Durable persistence for the operator's data-usage POLICY (cycle day + advisory
+// threshold), the write-side counterpart of `store.ts`'s counter persistence.
+//
+// WHY THIS IS LOCAL STATE AND NOT A MODEM WRITE. ModemManager has no data-usage
+// API at all. Verified against a live MM 1.24.2 (`mmcli --help-all`, plus a D-Bus
+// introspection of a real `…/ModemManager1/Modem/N`): the only `Setup`/threshold
+// surface on the whole object is `Modem.Signal.Setup` /
+// `Modem.Signal.SetupThresholds`, whose keys are `rssi-threshold` and
+// `error-rate-threshold` — RADIO QUALITY, not bytes. The only byte counters MM
+// offers are the per-BEARER read-only `Stats` (`rx-bytes`/`tx-bytes`), which
+// reset with every connection and therefore cannot carry a monthly cycle.
+//
+// That is exactly why the sampler in this directory counts `/proc/net/dev`
+// instead, and why `ports/README.md`'s ownership table records usage policy as
+// LOCAL-CONTROLLER owned. So the write path is a local, versioned, fail-soft
+// file — never a D-Bus mutation. (`Modem.Signal.Setup` is additionally forbidden
+// outright by the shadow-mode mutation-freedom contract; nothing here goes near
+// it.)
+//
+// The two hard guarantees are the SAME ones `store.ts` makes, and deliberately
+// implemented the same way so the pair can be read side by side:
+//   - MODE 0600 via temp → chmod → atomic rename, regardless of umask.
+//   - FAIL-SOFT ON CORRUPTION: an unparseable/incompatible file logs METADATA
+//     ONLY (byte length + a classification reason, never the content) and is
+//     replaced by a fresh empty 0600 file rather than throwing.
+//
+// A policy row carries ONLY an opaque slot id and two numbers. By construction
+// there is no subscriber or device identity here (no ICCID/IMSI/IMEI, no
+// operator, no model) — the same no-PII property the counter store holds.
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** The current on-disk schema version. Bump when the persisted shape changes. */
+export const USAGE_POLICY_SCHEMA_VERSION = 1;
+function defaultLogger(event) {
+    console.warn(`[usage-policy] ${event.kind}: bytes=${event.bytes} reason=${event.reason}`);
+}
+function freshState(nowMs) {
+    return { schemaVersion: USAGE_POLICY_SCHEMA_VERSION, savedAtMs: nowMs, slots: [] };
+}
+/** A schema violation naming only the offending FIELD (never file content). */
+class PolicySchemaError extends Error {
+    constructor(field) {
+        super(`schema-mismatch: ${field}`);
+    }
+}
+/** True for a value that is a legal cycle day (integer 1–31). */
+export function isValidCycleDay(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 31;
+}
+/** True for a value that is a legal advisory threshold (non-negative integer). */
+export function isValidThresholdBytes(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+function validateSlot(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new PolicySchemaError('slot');
+    }
+    const slot = raw;
+    if (typeof slot.logicalSlotId !== 'string' || slot.logicalSlotId.length === 0) {
+        throw new PolicySchemaError('logicalSlotId');
+    }
+    if (slot.cycleDay !== undefined && !isValidCycleDay(slot.cycleDay)) {
+        throw new PolicySchemaError('cycleDay');
+    }
+    if (slot.thresholdBytes !== undefined && !isValidThresholdBytes(slot.thresholdBytes)) {
+        throw new PolicySchemaError('thresholdBytes');
+    }
+    return {
+        logicalSlotId: slot.logicalSlotId,
+        ...(slot.cycleDay !== undefined ? { cycleDay: slot.cycleDay } : {}),
+        ...(slot.thresholdBytes !== undefined ? { thresholdBytes: slot.thresholdBytes } : {}),
+    };
+}
+/** Parse + validate the document. Throws `PolicySchemaError` (metadata-only). */
+function validate(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new PolicySchemaError('document');
+    }
+    const doc = raw;
+    if (doc.schemaVersion !== USAGE_POLICY_SCHEMA_VERSION) {
+        throw new PolicySchemaError('schemaVersion');
+    }
+    if (typeof doc.savedAtMs !== 'number' || !Number.isFinite(doc.savedAtMs)) {
+        throw new PolicySchemaError('savedAtMs');
+    }
+    if (!Array.isArray(doc.slots)) {
+        throw new PolicySchemaError('slots');
+    }
+    return {
+        schemaVersion: USAGE_POLICY_SCHEMA_VERSION,
+        savedAtMs: doc.savedAtMs,
+        slots: doc.slots.map(validateSlot),
+    };
+}
+/** Classify a load failure into a metadata-only reason string (no raw content). */
+function classifyFailure(error) {
+    if (error instanceof PolicySchemaError) {
+        return error.message;
+    }
+    if (error instanceof SyntaxError) {
+        const offset = /position (\d+)/.exec(error.message)?.[1];
+        return offset !== undefined ? `invalid-json at offset ${offset}` : 'invalid-json';
+    }
+    return 'unreadable';
+}
+/**
+ * Read one slot's policy out of a loaded document.
+ *
+ * This is the read half the composition root uses to build each slot's
+ * `UsageObservation.usage`, so the persisted file — not an in-memory guess — is
+ * what the sampler accounts against. An unknown slot answers `{}`, i.e. "no
+ * policy set", which is exactly what `defaultCellularPolicy` starts from.
+ */
+export function selectUsagePolicy(state, logicalSlotId) {
+    const slot = state.slots.find((entry) => entry.logicalSlotId === logicalSlotId);
+    if (slot === undefined) {
+        return {};
+    }
+    return {
+        ...(slot.cycleDay !== undefined ? { cycleDay: slot.cycleDay } : {}),
+        ...(slot.thresholdBytes !== undefined ? { thresholdBytes: slot.thresholdBytes } : {}),
+    };
+}
+export function createUsagePolicyFileStore(options) {
+    const logger = options.logger ?? defaultLogger;
+    const { path } = options;
+    async function writeAtomic(state) {
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp`;
+        await writeFile(tmp, JSON.stringify(state));
+        // chmod AFTER the write (not an open flag) so mode is 0600 regardless of umask.
+        await chmod(tmp, 0o600);
+        await rename(tmp, path);
+    }
+    return {
+        async load(nowMs) {
+            let text;
+            try {
+                text = await readFile(path, 'utf8');
+            }
+            catch {
+                // Absent (or unreadable) → start empty; the first save lays down a 0600 file.
+                return freshState(nowMs);
+            }
+            try {
+                return validate(JSON.parse(text));
+            }
+            catch (error) {
+                logger({
+                    kind: 'corrupt-policy',
+                    bytes: Buffer.byteLength(text, 'utf8'),
+                    reason: classifyFailure(error),
+                });
+                const fresh = freshState(nowMs);
+                await writeAtomic(fresh);
+                return fresh;
+            }
+        },
+        save: writeAtomic,
+    };
+}

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

@@ -0,0 +1,65 @@
+import type { DesiredUsage } from '../../domain/index.js';
+import { type UsagePolicyStore } from './policy-store.js';
+/**
+ * The live-apply seam. `UsageSampler` implements it; a caller with no running
+ * sampler simply omits it and the write is persistence-only.
+ */
+export interface UsagePolicyTarget {
+    applyUsagePolicy(logicalSlotId: string, usage: DesiredUsage, atMs?: number): UsagePolicyApplication;
+}
+/** What a live apply did to the slot's accounting window. */
+export interface UsagePolicyApplication {
+    /** The UTC start of the cycle the slot is now accruing into. */
+    readonly cycleStartMs: number;
+    /** True when the cycle ANCHOR moved, so the per-cycle total restarted at 0. */
+    readonly cycleReset: boolean;
+}
+export interface SetUsagePolicyDeps {
+    readonly store: UsagePolicyStore;
+    /** Optional live sampler to apply the change to immediately. */
+    readonly sampler?: UsagePolicyTarget;
+    /** Injectable clock (defaults to `Date.now`). */
+    readonly now?: () => number;
+}
+/**
+ * The requested change.
+ *
+ * Tri-state per field, and the distinction is the whole point: `undefined`
+ * leaves the persisted value ALONE (so a caller changing only the threshold
+ * cannot silently drop a cycle day it never mentioned), while an explicit `null`
+ * CLEARS it. A caller that cannot express `null` can never unset a policy.
+ */
+export interface SetUsagePolicyRequest {
+    readonly logicalSlotId: string;
+    readonly cycleDay?: number | null;
+    readonly thresholdBytes?: number | null;
+}
+export type SetUsagePolicyRejection = 'invalid-slot-id' | 'invalid-cycle-day' | 'invalid-threshold-bytes';
+export type SetUsagePolicyResult = {
+    readonly status: 'applied';
+    readonly logicalSlotId: string;
+    /** The policy now persisted for this slot (post-merge). */
+    readonly usage: DesiredUsage;
+    /** Present only when a live sampler was supplied. */
+    readonly applied?: UsagePolicyApplication;
+} | {
+    readonly status: 'rejected';
+    readonly logicalSlotId: string;
+    readonly reason: SetUsagePolicyRejection;
+} | {
+    readonly status: 'failed';
+    readonly logicalSlotId: string;
+    readonly reason: string;
+};
+/**
+ * Persist a slot's usage policy and, when a live sampler is supplied, apply it
+ * to that sampler in the same call.
+ *
+ * ORDER IS LOAD → VALIDATE → PERSIST → APPLY, and it is deliberate. The store is
+ * the source of truth (the composition root rebuilds every `UsageObservation`
+ * from it), so a live apply that landed while the write failed would leave the
+ * running process disagreeing with what a restart would restore.
+ */
+export declare function setUsagePolicy(deps: SetUsagePolicyDeps, request: SetUsagePolicyRequest): Promise<SetUsagePolicyResult>;
+/** Read one slot's persisted policy. The read counterpart of `setUsagePolicy`. */
+export declare function getUsagePolicy(deps: Pick<SetUsagePolicyDeps, 'store' | 'now'>, logicalSlotId: string): Promise<DesiredUsage>;

package/dist/backend/usage/policy-write.js

@@ -0,0 +1,112 @@
+// `setUsagePolicy` — the WRITE half of the data-usage surface.
+//
+// The read half already existed (`UsageSampler.snapshot()` reports `cycleBytes`,
+// `thresholdBytes` and `thresholdExceeded`), but nothing could SET the two
+// numbers those readings are computed against: `DesiredUsage` was a shape the
+// planner echoed into a receipt, with no persistence and no apply path. This
+// module closes that, mirroring the read side's file-store idiom exactly.
+//
+// It is a LOCAL write, not a modem write — see `policy-store.ts`'s header for the
+// ModemManager API evidence. Nothing here touches D-Bus, `mmcli`, or any bearer.
+//
+// TYPED RESULTS, NEVER THROWS ON BAD INPUT. Following the `PowerHook` precedent
+// (`power-contract.ts`: `applied` / `unsupported` / `failed`), an out-of-range
+// day is a `rejected` result carrying a named reason rather than an exception —
+// this is called from an RPC boundary where a throw becomes an opaque 500.
+import { isValidCycleDay, isValidThresholdBytes, selectUsagePolicy, USAGE_POLICY_SCHEMA_VERSION, } from './policy-store.js';
+function validateRequest(request) {
+    if (typeof request.logicalSlotId !== 'string' || request.logicalSlotId.length === 0) {
+        return 'invalid-slot-id';
+    }
+    if (request.cycleDay !== undefined &&
+        request.cycleDay !== null &&
+        !isValidCycleDay(request.cycleDay)) {
+        return 'invalid-cycle-day';
+    }
+    if (request.thresholdBytes !== undefined &&
+        request.thresholdBytes !== null &&
+        !isValidThresholdBytes(request.thresholdBytes)) {
+        return 'invalid-threshold-bytes';
+    }
+    return undefined;
+}
+/** Fold the request onto the currently-persisted policy (tri-state merge). */
+function mergePolicy(current, request) {
+    const cycleDay = request.cycleDay === undefined ? current.cycleDay : (request.cycleDay ?? undefined);
+    const thresholdBytes = request.thresholdBytes === undefined
+        ? current.thresholdBytes
+        : (request.thresholdBytes ?? undefined);
+    return {
+        ...(cycleDay !== undefined ? { cycleDay } : {}),
+        ...(thresholdBytes !== undefined ? { thresholdBytes } : {}),
+    };
+}
+function toSlot(logicalSlotId, usage) {
+    return {
+        logicalSlotId,
+        ...(usage.cycleDay !== undefined ? { cycleDay: usage.cycleDay } : {}),
+        ...(usage.thresholdBytes !== undefined ? { thresholdBytes: usage.thresholdBytes } : {}),
+    };
+}
+/**
+ * Persist a slot's usage policy and, when a live sampler is supplied, apply it
+ * to that sampler in the same call.
+ *
+ * ORDER IS LOAD → VALIDATE → PERSIST → APPLY, and it is deliberate. The store is
+ * the source of truth (the composition root rebuilds every `UsageObservation`
+ * from it), so a live apply that landed while the write failed would leave the
+ * running process disagreeing with what a restart would restore.
+ */
+export async function setUsagePolicy(deps, request) {
+    const logicalSlotId = typeof request.logicalSlotId === 'string' ? request.logicalSlotId : '';
+    const rejection = validateRequest(request);
+    if (rejection !== undefined) {
+        return { status: 'rejected', logicalSlotId, reason: rejection };
+    }
+    const now = deps.now ?? Date.now;
+    const at = now();
+    let usage;
+    try {
+        const state = await deps.store.load(at);
+        usage = mergePolicy(selectUsagePolicy(state, logicalSlotId), request);
+        const others = state.slots.filter((slot) => slot.logicalSlotId !== logicalSlotId);
+        // An empty policy is REMOVED rather than stored as an empty row: "no policy"
+        // and "a policy that sets nothing" are the same fact, and keeping the row
+        // would grow the file by one entry per slot an operator ever cleared.
+        const slots = usage.cycleDay === undefined && usage.thresholdBytes === undefined
+            ? others
+            : [...others, toSlot(logicalSlotId, usage)];
+        await deps.store.save({
+            schemaVersion: USAGE_POLICY_SCHEMA_VERSION,
+            savedAtMs: at,
+            slots,
+        });
+    }
+    catch (error) {
+        return {
+            status: 'failed',
+            logicalSlotId,
+            reason: error instanceof Error ? error.message : 'persist-failed',
+        };
+    }
+    if (deps.sampler === undefined) {
+        return { status: 'applied', logicalSlotId, usage };
+    }
+    try {
+        const applied = deps.sampler.applyUsagePolicy(logicalSlotId, usage, at);
+        return { status: 'applied', logicalSlotId, usage, applied };
+    }
+    catch (error) {
+        return {
+            status: 'failed',
+            logicalSlotId,
+            reason: error instanceof Error ? error.message : 'apply-failed',
+        };
+    }
+}
+/** Read one slot's persisted policy. The read counterpart of `setUsagePolicy`. */
+export async function getUsagePolicy(deps, logicalSlotId) {
+    const now = deps.now ?? Date.now;
+    const state = await deps.store.load(now());
+    return selectUsagePolicy(state, logicalSlotId);
+}

package/dist/backend/usage/proc-net-dev.d.ts

@@ -0,0 +1,18 @@
+/** A source of cumulative rx+tx byte counters keyed by interface name. */
+export interface CounterSource {
+    /** Read the current cumulative rx+tx byte total for every interface. */
+    read(): Promise<ReadonlyMap<string, number>>;
+}
+/**
+ * Parse `/proc/net/dev` text into a map of interface name → cumulative rx+tx bytes.
+ * The two-line header is skipped; malformed or short rows are ignored rather than
+ * throwing, so a single odd line can never break sampling.
+ */
+export declare function parseProcNetDev(text: string): Map<string, number>;
+/**
+ * The production counter source: reads and parses the real `/proc/net/dev`. The
+ * path is injectable so tests can point at a fixture, but the default is the live
+ * kernel file. A missing/unreadable file yields an empty map (fail-soft — a read
+ * error never crashes the sampler; that pass simply attributes no new bytes).
+ */
+export declare function procNetDevCounterSource(path?: string): CounterSource;

package/{src/backend/usage/proc-net-dev.ts → dist/backend/usage/proc-net-dev.js}

@@ -11,67 +11,59 @@
 // accounting layer clamps). We parse the proc text ourselves rather than shelling
 // out to `ip`/`ifconfig` because the raw file is the most reliable, consistent
 // source and matches exactly what the plan names.
-
-/** A source of cumulative rx+tx byte counters keyed by interface name. */
-export interface CounterSource {
-	/** Read the current cumulative rx+tx byte total for every interface. */
-	read(): Promise<ReadonlyMap<string, number>>;
-}
-
 const HEADER_LINE_COUNT = 2;
 const RX_BYTES_COLUMN = 0;
 const TX_BYTES_COLUMN = 8;
 const MIN_COLUMNS = TX_BYTES_COLUMN + 1;
-
 /**
  * Parse `/proc/net/dev` text into a map of interface name → cumulative rx+tx bytes.
  * The two-line header is skipped; malformed or short rows are ignored rather than
  * throwing, so a single odd line can never break sampling.
  */
-export function parseProcNetDev(text: string): Map<string, number> {
-	const counters = new Map<string, number>();
-	const lines = text.split('\n').slice(HEADER_LINE_COUNT);
-	for (const line of lines) {
-		const colon = line.indexOf(':');
-		if (colon < 0) {
-			continue;
-		}
-		const ifname = line.slice(0, colon).trim();
-		if (ifname.length === 0) {
-			continue;
-		}
-		const columns = line
-			.slice(colon + 1)
-			.trim()
-			.split(/\s+/);
-		if (columns.length < MIN_COLUMNS) {
-			continue;
-		}
-		const rx = Number(columns[RX_BYTES_COLUMN]);
-		const tx = Number(columns[TX_BYTES_COLUMN]);
-		if (!Number.isFinite(rx) || !Number.isFinite(tx) || rx < 0 || tx < 0) {
-			continue;
-		}
-		counters.set(ifname, rx + tx);
-	}
-	return counters;
+export function parseProcNetDev(text) {
+    const counters = new Map();
+    const lines = text.split('\n').slice(HEADER_LINE_COUNT);
+    for (const line of lines) {
+        const colon = line.indexOf(':');
+        if (colon < 0) {
+            continue;
+        }
+        const ifname = line.slice(0, colon).trim();
+        if (ifname.length === 0) {
+            continue;
+        }
+        const columns = line
+            .slice(colon + 1)
+            .trim()
+            .split(/\s+/);
+        if (columns.length < MIN_COLUMNS) {
+            continue;
+        }
+        const rx = Number(columns[RX_BYTES_COLUMN]);
+        const tx = Number(columns[TX_BYTES_COLUMN]);
+        if (!Number.isFinite(rx) || !Number.isFinite(tx) || rx < 0 || tx < 0) {
+            continue;
+        }
+        counters.set(ifname, rx + tx);
+    }
+    return counters;
 }
-
 /**
  * The production counter source: reads and parses the real `/proc/net/dev`. The
  * path is injectable so tests can point at a fixture, but the default is the live
  * kernel file. A missing/unreadable file yields an empty map (fail-soft — a read
  * error never crashes the sampler; that pass simply attributes no new bytes).
  */
-export function procNetDevCounterSource(path = '/proc/net/dev'): CounterSource {
-	return {
-		async read(): Promise<ReadonlyMap<string, number>> {
-			try {
-				const text = await Bun.file(path).text();
-				return parseProcNetDev(text);
-			} catch {
-				return new Map();
-			}
-		},
-	};
+export function procNetDevCounterSource(path = '/proc/net/dev') {
+    return {
+        async read() {
+            try {
+                const text = await Bun.file(path).text();
+                return parseProcNetDev(text);
+            }
+            catch {
+                return new Map();
+            }
+        },
+    };
 }

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

@@ -0,0 +1,75 @@
+import { type DesiredUsage, type 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. */
+export interface UsageObservation {
+    readonly logicalSlotId: LogicalSlotId;
+    /** Bumped by A4.2 whenever the ifname-to-slot mapping changes (→ zero-delta rebase). */
+    readonly mappingGeneration: number;
+    readonly ifname: string;
+    /** A3.2 identity-ladder confidence; `low` pauses sampling for this slot. */
+    readonly confidence: 'high' | 'medium' | 'low';
+    /** Local-controller-owned usage policy (cycle day + advisory threshold). */
+    readonly usage: DesiredUsage;
+}
+/** A queryable per-slot usage figure — consumed by the A6.1 bench CLI `usage` command. */
+export interface SlotUsageSnapshot {
+    readonly logicalSlotId: string;
+    readonly cycleBytes: number;
+    readonly cycleStartMs: number;
+    readonly paused: boolean;
+    /** The cycle day in force for this slot, when the operator set one. */
+    readonly cycleDay?: number;
+    readonly thresholdBytes?: number;
+    /** Advisory-only: `cycleBytes > thresholdBytes`. Never gates the connection. */
+    readonly thresholdExceeded: boolean;
+}
+/** The sampler's current state, per slot, at a point in time. */
+export interface UsageSnapshot {
+    readonly bootId: string;
+    readonly generatedAtMs: number;
+    readonly slots: readonly SlotUsageSnapshot[];
+}
+export interface UsageSamplerOptions {
+    /** The kernel boot id (see `readBootId`) — the session identity. */
+    readonly bootId: string;
+    readonly source: CounterSource;
+    readonly store: UsageStore;
+    /** Injectable clock (defaults to `Date.now`). */
+    readonly now?: () => number;
+    /** Minimum spacing between persists (default 60_000 ms = the ≤1-min loss bound). */
+    readonly persistIntervalMs?: number;
+    /** Cycle day used when a slot's policy omits `cycleDay` (default 1 = 1st of month). */
+    readonly defaultCycleDay?: number;
+}
+export declare class UsageSampler {
+    #private;
+    private constructor();
+    /** Load persisted state (recreating a fresh file if absent/corrupt) then build the sampler. */
+    static create(options: UsageSamplerOptions): Promise<UsageSampler>;
+    /** Take one sampling pass over the current counters for the given observations. */
+    sample(observations: readonly UsageObservation[]): Promise<void>;
+    /** Current per-slot usage — the queryable snapshot the CLI and platform read. */
+    snapshot(): UsageSnapshot;
+    /**
+     * Apply an operator's usage policy to this slot immediately, without waiting
+     * for the next sampling pass.
+     *
+     * A CHANGED CYCLE ANCHOR RESTARTS THE WINDOW AT ZERO, and keeps the counter
+     * BASELINE. Those two halves are the honest answer to a question with no
+     * truthful one: bytes already accrued were measured under the OLD window, so
+     * carrying them into the new one over-reports it, and there is no record of
+     * how they were distributed within it. Starting fresh states plainly that the
+     * new window began now; keeping `lastObserved` means the next sample still
+     * attributes only genuinely new bytes, never a jump. A threshold-only change
+     * moves no anchor and therefore resets nothing.
+     */
+    applyUsagePolicy(logicalSlotId: string, usage: DesiredUsage, atMs?: number): {
+        cycleStartMs: number;
+        cycleReset: boolean;
+    };
+    /** Flush unpersisted state immediately — the shutdown hook (bounds loss to ≤1 min). */
+    flush(): Promise<void>;
+}
+/** Load persisted state and build a ready sampler. See `UsageSampler.create`. */
+export declare function createUsageSampler(options: UsageSamplerOptions): Promise<UsageSampler>;