@ceralive/modem-control 0.2.0 → 1.1.0

package/src/backend/usage/accounting.test.ts

@@ -1,147 +0,0 @@
-// The adversarial accounting matrix — pure, deterministic proofs that per-slot usage
-// is attributed correctly across remaps, swaps, reuse, resets, pauses, and rollovers.
-
-import { describe, expect, test } from 'bun:test';
-import { type IdentityConfidence, logicalSlotId } from '../../domain';
-import { applySample, type BaselineKey, type SlotAccount } from './accounting';
-
-const SLOT_A = logicalSlotId('slot-a');
-const SLOT_B = logicalSlotId('slot-b');
-const SLOT_C = logicalSlotId('slot-c');
-const BOOT = 'boot-uuid-1';
-
-interface Step {
-	readonly slot: string;
-	readonly gen: number;
-	readonly ifname: string;
-	readonly current: number;
-	readonly confidence?: IdentityConfidence;
-	readonly cycleStartMs?: number;
-}
-
-function key(slot: string, gen: number, ifname: string): BaselineKey {
-	return { logicalSlotId: slot, mappingGeneration: gen, ifname, bootId: BOOT };
-}
-
-function step(prior: SlotAccount | undefined, s: Step): SlotAccount {
-	return applySample(prior, {
-		key: key(s.slot, s.gen, s.ifname),
-		current: s.current,
-		confidence: s.confidence ?? 'high',
-		cycleStartMs: s.cycleStartMs ?? 1000,
-	});
-}
-
-describe('applySample — two modems tracked independently', () => {
-	test('separate slots never cross-contaminate', () => {
-		let a = step(undefined, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 100 });
-		let b = step(undefined, { slot: SLOT_B, gen: 0, ifname: 'wwan1', current: 5000 });
-		a = step(a, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 300 });
-		b = step(b, { slot: SLOT_B, gen: 0, ifname: 'wwan1', current: 5001 });
-		expect(a.cycleBytes).toBe(200);
-		expect(b.cycleBytes).toBe(1);
-	});
-});
-
-describe('applySample — A/B ifname swap follows the slot, not the interface', () => {
-	test('each slot keeps its own total across a swap and re-baselines zero-delta', () => {
-		// Prime: A on wwan0, B on wwan1.
-		let a = step(undefined, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 100 });
-		let b = step(undefined, { slot: SLOT_B, gen: 0, ifname: 'wwan1', current: 1000 });
-		a = step(a, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 200 });
-		b = step(b, { slot: SLOT_B, gen: 0, ifname: 'wwan1', current: 1100 });
-		expect(a.cycleBytes).toBe(100);
-		expect(b.cycleBytes).toBe(100);
-
-		// Swap: A now maps to wwan1, B to wwan0 (mapping generation bumps for both).
-		// First post-swap sample must be zero-delta despite the large counter change.
-		a = step(a, { slot: SLOT_A, gen: 1, ifname: 'wwan1', current: 1100 });
-		b = step(b, { slot: SLOT_B, gen: 1, ifname: 'wwan0', current: 200 });
-		expect(a.cycleBytes).toBe(100);
-		expect(b.cycleBytes).toBe(100);
-
-		// Subsequent growth attributes to the correct slot on its new interface.
-		a = step(a, { slot: SLOT_A, gen: 1, ifname: 'wwan1', current: 1150 });
-		b = step(b, { slot: SLOT_B, gen: 1, ifname: 'wwan0', current: 260 });
-		expect(a.cycleBytes).toBe(150);
-		expect(b.cycleBytes).toBe(160);
-	});
-});
-
-describe('applySample — old ifname reused by a different slot (no bleed)', () => {
-	test('a new slot inheriting an old interface starts from zero', () => {
-		let a = step(undefined, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 100 });
-		a = step(a, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 500 });
-		expect(a.cycleBytes).toBe(400);
-
-		// Slot C now occupies wwan0. Its own account starts fresh (zero-delta baseline).
-		let c = step(undefined, { slot: SLOT_C, gen: 0, ifname: 'wwan0', current: 500 });
-		c = step(c, { slot: SLOT_C, gen: 0, ifname: 'wwan0', current: 700 });
-		expect(c.cycleBytes).toBe(200);
-		// A's total is untouched — no bleed either direction.
-		expect(a.cycleBytes).toBe(400);
-	});
-});
-
-describe('applySample — rename-first-sample is zero-delta', () => {
-	test('the first sample after a remap never reports a spurious jump', () => {
-		let s = step(undefined, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 100 });
-		s = step(s, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 200 });
-		expect(s.cycleBytes).toBe(100);
-		// Rename wwan0 → wwan5 with a huge counter: must NOT attribute 9M.
-		s = step(s, { slot: SLOT_A, gen: 1, ifname: 'wwan5', current: 9_000_000 });
-		expect(s.cycleBytes).toBe(100);
-	});
-});
-
-describe('applySample — reset-then-positive', () => {
-	test('a counter reset clamps to zero, then normal increases resume', () => {
-		let s = step(undefined, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 1000 });
-		s = step(s, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 1500 });
-		expect(s.cycleBytes).toBe(500);
-		// Interface recreated: counter drops to 50 (decrease) → clamp + rebase.
-		s = step(s, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 50 });
-		expect(s.cycleBytes).toBe(500);
-		// Growth from the rebased baseline is tracked again.
-		s = step(s, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 250 });
-		expect(s.cycleBytes).toBe(700);
-	});
-
-	test('a decrease never produces a negative delta', () => {
-		let s = step(undefined, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 800 });
-		s = step(s, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 300 });
-		expect(s.cycleBytes).toBe(0);
-		expect(s.cycleBytes).toBeGreaterThanOrEqual(0);
-	});
-});
-
-describe('applySample — ambiguous identity pauses sampling', () => {
-	test('low confidence attributes nothing and re-baselines zero-delta on resume', () => {
-		let s = step(undefined, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 100 });
-		s = step(s, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 300 });
-		expect(s.cycleBytes).toBe(200);
-		// Identity turns ambiguous → paused; the counter keeps climbing unattributed.
-		s = step(s, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 9999, confidence: 'low' });
-		expect(s.paused).toBe(true);
-		expect(s.cycleBytes).toBe(200);
-		// Confidence returns: resume is zero-delta, so the paused-window bytes are NOT
-		// back-attributed; only growth after resume counts.
-		s = step(s, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 9999 });
-		expect(s.paused).toBe(false);
-		expect(s.cycleBytes).toBe(200);
-		s = step(s, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 10_099 });
-		expect(s.cycleBytes).toBe(300);
-	});
-});
-
-describe('applySample — cycle rollover resets the per-cycle total', () => {
-	test('crossing into a newer cycle zeroes cycleBytes but keeps the baseline', () => {
-		let s = step(undefined, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 100 });
-		s = step(s, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 600 });
-		expect(s.cycleBytes).toBe(500);
-		// New cycle boundary — cycleBytes resets, counter continuity preserved.
-		s = step(s, { slot: SLOT_A, gen: 0, ifname: 'wwan0', current: 650, cycleStartMs: 2000 });
-		expect(s.cycleStartMs).toBe(2000);
-		expect(s.cycleBytes).toBe(50);
-	});
-});

package/src/backend/usage/accounting.ts

@@ -1,123 +0,0 @@
-// 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.
-
-import type { IdentityConfidence, LogicalSlotId } from '../../domain';
-
-/** 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 function initialAccount(cycleStartMs: number): SlotAccount {
-	return { cycleBytes: 0, cycleStartMs, paused: false };
-}
-
-function sameKey(a: BaselineKey, b: BaselineKey): boolean {
-	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: SlotAccount, cycleStartMs: number): SlotAccount {
-	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: SlotAccount | undefined, input: SampleInput): SlotAccount {
-	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: LogicalSlotId,
-	mappingGeneration: number,
-	ifname: string,
-	bootId: string,
-): BaselineKey {
-	return { logicalSlotId, mappingGeneration, ifname, bootId };
-}

package/src/backend/usage/billing-cycle.test.ts

@@ -1,62 +0,0 @@
-// UTC billing-cycle math — month-length clamping (cycleDay 31 → Feb 28/29) and the
-// before/after-boundary cycle-start selection.
-
-import { describe, expect, test } from 'bun:test';
-import { type EpochMillis, epochMillis } from '../../domain';
-import { clampCycleDay, cycleStart, daysInMonth } from './billing-cycle';
-
-const utc = (y: number, m: number, d: number, h = 0): EpochMillis =>
-	epochMillis(Date.UTC(y, m, d, h));
-
-describe('daysInMonth', () => {
-	test('February is 28 days in a common year, 29 in a leap year', () => {
-		expect(daysInMonth(2023, 1)).toBe(28);
-		expect(daysInMonth(2024, 1)).toBe(29); // 2024 is a leap year
-		expect(daysInMonth(2100, 1)).toBe(28); // century non-leap
-		expect(daysInMonth(2000, 1)).toBe(29); // 400-divisible leap
-	});
-
-	test('30- and 31-day months', () => {
-		expect(daysInMonth(2024, 3)).toBe(30); // April
-		expect(daysInMonth(2024, 0)).toBe(31); // January
-	});
-});
-
-describe('clampCycleDay', () => {
-	test('cycleDay 31 clamps to the last day of a short month', () => {
-		expect(clampCycleDay(31, 2023, 1)).toBe(28); // Feb non-leap
-		expect(clampCycleDay(31, 2024, 1)).toBe(29); // Feb leap
-		expect(clampCycleDay(31, 2024, 3)).toBe(30); // April
-		expect(clampCycleDay(31, 2024, 0)).toBe(31); // January — no clamp
-	});
-
-	test('a valid in-range day is unchanged; a floor of 1 is enforced', () => {
-		expect(clampCycleDay(15, 2024, 5)).toBe(15);
-		expect(clampCycleDay(0, 2024, 5)).toBe(1);
-	});
-});
-
-describe('cycleStart — month-length clamp with before/after selection', () => {
-	test('cycleDay 31 in February resolves to the clamped Feb boundary', () => {
-		// 2023-02-15 with cycleDay 31 → cycle started 2023-01-31 (Feb boundary Feb 28
-		// is still ahead of the 15th).
-		expect(cycleStart(epochMillis(utc(2023, 1, 15)), 31)).toBe(utc(2023, 0, 31));
-		// 2023-03-01 with cycleDay 31 → the active cycle began at clamped Feb 28.
-		expect(cycleStart(epochMillis(utc(2023, 2, 1)), 31)).toBe(utc(2023, 1, 28));
-		// Leap year: 2024-03-01 → Feb 29.
-		expect(cycleStart(epochMillis(utc(2024, 2, 1)), 31)).toBe(utc(2024, 1, 29));
-	});
-
-	test('now exactly on the boundary starts a new cycle', () => {
-		expect(cycleStart(epochMillis(utc(2024, 5, 10)), 10)).toBe(utc(2024, 5, 10));
-	});
-
-	test('now before this month boundary rolls back to the previous month', () => {
-		// cycleDay 20, now is the 5th → cycle began on the 20th of the prior month.
-		expect(cycleStart(epochMillis(utc(2024, 6, 5)), 20)).toBe(utc(2024, 5, 20));
-	});
-
-	test('January rollback wraps to December of the prior year', () => {
-		expect(cycleStart(epochMillis(utc(2024, 0, 5)), 20)).toBe(utc(2023, 11, 20));
-	});
-});

package/src/backend/usage/billing-cycle.ts

@@ -1,45 +0,0 @@
-// 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.
-
-import type { EpochMillis } from '../../domain';
-
-/** Days in a given UTC month. `month` is 0-based (0 = January). Handles leap Feb. */
-export function daysInMonth(year: number, month: number): number {
-	// 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: number, year: number, month: number): number {
-	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: number, year: number, month: number): number {
-	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: EpochMillis, cycleDay: number): EpochMillis {
-	const at = new Date(now);
-	const year = at.getUTCFullYear();
-	const month = at.getUTCMonth();
-	const thisBoundary = boundaryFor(cycleDay, year, month);
-	if (now >= thisBoundary) {
-		return thisBoundary as EpochMillis;
-	}
-	// 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) as EpochMillis;
-}

package/src/backend/usage/index.ts

@@ -1,37 +0,0 @@
-// 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,
-	type BaselineKey,
-	baselineKey,
-	initialAccount,
-	type SampleInput,
-	type SlotAccount,
-} from './accounting';
-export { clampCycleDay, cycleStart, daysInMonth } from './billing-cycle';
-export { readBootId } from './boot-id';
-export {
-	type CounterSource,
-	parseProcNetDev,
-	procNetDevCounterSource,
-} from './proc-net-dev';
-export {
-	createUsageSampler,
-	type SlotUsageSnapshot,
-	type UsageObservation,
-	UsageSampler,
-	type UsageSamplerOptions,
-	type UsageSnapshot,
-} from './sampler';
-export {
-	createUsageFileStore,
-	type PersistedSlot,
-	type PersistedUsage,
-	USAGE_SCHEMA_VERSION,
-	type UsageFileStoreOptions,
-	type UsageLogEvent,
-	type UsageLogger,
-	type UsageStore,
-} from './store';

package/src/backend/usage/proc-net-dev.test.ts

@@ -1,56 +0,0 @@
-// `/proc/net/dev` parser — proves rx+tx cumulative totals over the real fixed-column
-// format, header skipping, and fail-soft handling of malformed rows.
-
-import { describe, expect, test } from 'bun:test';
-import { parseProcNetDev } from './proc-net-dev';
-
-// A real capture (columns: rx bytes packets errs drop fifo frame compressed multicast
-// | tx bytes packets errs drop fifo colls carrier compressed).
-const REAL = `Inter-|   Receive                                                |  Transmit
- face |bytes    packets errs drop fifo frame compressed multicast|bytes    packets errs drop fifo colls carrier compressed
-    lo: 160183007830 18519510    0    0    0     0          0         0 160183007830 18519510    0    0    0     0       0          0
-  eno2: 88166142004 86575608    0    0   48     0          0    146660 25843393633 48414413    0    3    0     0       0          0
- wlan0: 44865976  194892    0    0    0     0          0         0  5698312   36057    0   23    0     0       0          0
-`;
-
-describe('parseProcNetDev', () => {
-	test('reads rx+tx cumulative bytes for each interface, skipping the 2-line header', () => {
-		const counters = parseProcNetDev(REAL);
-		expect(counters.size).toBe(3);
-		// lo: 160183007830 (rx) + 160183007830 (tx).
-		expect(counters.get('lo')).toBe(160183007830 + 160183007830);
-		// eno2: rx 88166142004 + tx 25843393633.
-		expect(counters.get('eno2')).toBe(88166142004 + 25843393633);
-		// wlan0: rx 44865976 + tx 5698312.
-		expect(counters.get('wlan0')).toBe(44865976 + 5698312);
-	});
-
-	test('handles bridge-style names with no leading space and long names', () => {
-		const text = `h1
-h2
-br-d739ee545df1: 575402021  542380    0    0    0     0          0         0 450821722  810015    0    4    0     0       0          0
-docker0: 1750867165 1097738    0    0    0     0          0         0 5810268898 1237921    0 12223    0     0       0          0
-`;
-		const counters = parseProcNetDev(text);
-		expect(counters.get('br-d739ee545df1')).toBe(575402021 + 450821722);
-		expect(counters.get('docker0')).toBe(1750867165 + 5810268898);
-	});
-
-	test('ignores malformed / short rows without throwing', () => {
-		const text = `h1
-h2
-    lo: 100 1 0 0 0 0 0 0 200 2 0 0 0 0 0 0
-garbage-without-colon 1 2 3
-  short: 1 2 3
-   nan: x 1 0 0 0 0 0 0 y 2 0 0 0 0 0 0
-`;
-		const counters = parseProcNetDev(text);
-		// Only the well-formed `lo` row survives.
-		expect(counters.size).toBe(1);
-		expect(counters.get('lo')).toBe(300);
-	});
-
-	test('empty input yields an empty map', () => {
-		expect(parseProcNetDev('').size).toBe(0);
-	});
-});