@ceralive/modem-control 0.1.0 → 1.0.0

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

@@ -217,3 +217,111 @@ describe('UsageSampler — reboot (new boot id) re-baselines without losing the
 		expect(rebooted.snapshot().slots[0]?.cycleBytes).toBe(350);
 	});
 });
+
+describe('UsageSampler — applyUsagePolicy (the setUsagePolicy live-apply seam)', () => {
+	const AUG_16 = Date.UTC(2026, 7, 16, 12, 0, 0);
+
+	async function samplerAt(now: number) {
+		const counters = new FakeCounters();
+		const sampler = await createUsageSampler({
+			bootId: 'boot-1',
+			source: counters,
+			store: new MemStore(),
+			now: () => now,
+		});
+		return { counters, sampler };
+	}
+
+	test('a threshold-only change takes effect immediately and resets nothing', async () => {
+		const { counters, sampler } = await samplerAt(AUG_16);
+		counters.set('wwan0', 100);
+		await sampler.sample([obs(SLOT_A, 'wwan0')]);
+		counters.set('wwan0', 900);
+		await sampler.sample([obs(SLOT_A, 'wwan0')]);
+
+		const applied = sampler.applyUsagePolicy(SLOT_A, { thresholdBytes: 500 });
+
+		expect(applied.cycleReset).toBe(false);
+		const slot = sampler.snapshot().slots[0];
+		expect(slot?.cycleBytes).toBe(800);
+		expect(slot?.thresholdBytes).toBe(500);
+		expect(slot?.thresholdExceeded).toBe(true);
+	});
+
+	test('a CHANGED cycle day restarts the window at zero and re-anchors it', async () => {
+		const { counters, sampler } = await samplerAt(AUG_16);
+		counters.set('wwan0', 100);
+		await sampler.sample([obs(SLOT_A, 'wwan0')]);
+		counters.set('wwan0', 900);
+		await sampler.sample([obs(SLOT_A, 'wwan0')]);
+		expect(sampler.snapshot().slots[0]?.cycleBytes).toBe(800);
+
+		const applied = sampler.applyUsagePolicy(SLOT_A, { cycleDay: 20 });
+
+		expect(applied.cycleReset).toBe(true);
+		expect(applied.cycleStartMs).toBe(Date.UTC(2026, 6, 20));
+		const slot = sampler.snapshot().slots[0];
+		expect(slot?.cycleBytes).toBe(0);
+		expect(slot?.cycleStartMs).toBe(Date.UTC(2026, 6, 20));
+		expect(slot?.cycleDay).toBe(20);
+	});
+
+	test('the BASELINE survives the reset, so the next sample attributes no jump', async () => {
+		const { counters, sampler } = await samplerAt(AUG_16);
+		counters.set('wwan0', 1_000_000);
+		await sampler.sample([obs(SLOT_A, 'wwan0')]);
+
+		sampler.applyUsagePolicy(SLOT_A, { cycleDay: 20 });
+		counters.set('wwan0', 1_000_150);
+		await sampler.sample([obs(SLOT_A, 'wwan0', { cycleDay: 20 })]);
+
+		expect(sampler.snapshot().slots[0]?.cycleBytes).toBe(150);
+	});
+
+	test('re-applying the SAME cycle day is a no-op — repeated saves never zero a window', async () => {
+		const { counters, sampler } = await samplerAt(AUG_16);
+		counters.set('wwan0', 100);
+		await sampler.sample([obs(SLOT_A, 'wwan0', { cycleDay: 20 })]);
+		counters.set('wwan0', 400);
+		await sampler.sample([obs(SLOT_A, 'wwan0', { cycleDay: 20 })]);
+
+		const applied = sampler.applyUsagePolicy(SLOT_A, { cycleDay: 20 });
+
+		expect(applied.cycleReset).toBe(false);
+		expect(sampler.snapshot().slots[0]?.cycleBytes).toBe(300);
+	});
+
+	test('an applied policy OUTRANKS a stale observation on the next sample', async () => {
+		const { counters, sampler } = await samplerAt(AUG_16);
+		counters.set('wwan0', 100);
+		await sampler.sample([obs(SLOT_A, 'wwan0', { thresholdBytes: 10 })]);
+
+		sampler.applyUsagePolicy(SLOT_A, { thresholdBytes: 999 });
+		// The composition root has not rebuilt its observations yet and still
+		// carries the OLD policy — the write must not silently revert.
+		await sampler.sample([obs(SLOT_A, 'wwan0', { thresholdBytes: 10 })]);
+
+		expect(sampler.snapshot().slots[0]?.thresholdBytes).toBe(999);
+	});
+
+	test('applying to a slot never sampled creates it without claiming any bytes', async () => {
+		const { sampler } = await samplerAt(AUG_16);
+
+		const applied = sampler.applyUsagePolicy(SLOT_B, { cycleDay: 3, thresholdBytes: 7 });
+
+		expect(applied.cycleReset).toBe(false);
+		const slot = sampler.snapshot().slots[0];
+		expect(slot?.logicalSlotId).toBe('slot-b');
+		expect(slot?.cycleBytes).toBe(0);
+		expect(slot?.cycleDay).toBe(3);
+		expect(slot?.thresholdBytes).toBe(7);
+	});
+
+	test('a slot with no policy reports no cycleDay rather than the sampler default', async () => {
+		const { counters, sampler } = await samplerAt(AUG_16);
+		counters.set('wwan0', 10);
+		await sampler.sample([obs(SLOT_A, 'wwan0')]);
+
+		expect(sampler.snapshot().slots[0]?.cycleDay).toBeUndefined();
+	});
+});

package/src/backend/usage/sampler.ts

@@ -36,6 +36,8 @@ export interface SlotUsageSnapshot {
 	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;
@@ -85,6 +87,13 @@ export class UsageSampler {
 	readonly #defaultCycleDay: number;
 	readonly #accounts = new Map<string, SlotAccount>();
 	readonly #policies = new Map<string, DesiredUsage>();
+	// Policies written through `applyUsagePolicy` OUTRANK whatever an observation
+	// carries, for the life of the process. Without this, the next `sample()` would
+	// clobber a just-applied write with the policy the composition root happened to
+	// build its observation from — and the operator would watch their setting
+	// revert. The durable store is the source of truth for both, so an override and
+	// an observation can only ever disagree inside that window.
+	readonly #policyOverrides = new Map<string, DesiredUsage>();
 	#lastPersistMs: number;
 	#dirty = false;
 
@@ -145,8 +154,9 @@ export class UsageSampler {
 		const now = this.#now();
 		for (const obs of observations) {
 			const slotId = obs.logicalSlotId as string;
-			this.#policies.set(slotId, obs.usage);
-			const cycleDay = obs.usage.cycleDay ?? this.#defaultCycleDay;
+			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) {
@@ -179,12 +189,14 @@ export class UsageSampler {
 		const generatedAtMs = this.#now();
 		const slots: SlotUsageSnapshot[] = [];
 		for (const [slotId, account] of this.#accounts) {
-			const thresholdBytes = this.#policies.get(slotId)?.thresholdBytes;
+			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,
 			});
@@ -192,6 +204,48 @@ export class UsageSampler {
 		return { bootId: this.#bootId, generatedAtMs, slots };
 	}
 
+	/**
+	 * 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;
+	} {
+		const now = atMs ?? this.#now();
+		this.#policyOverrides.set(logicalSlotId, usage);
+		this.#policies.set(logicalSlotId, usage);
+		const cycleStartMs = cycleStart(
+			epochMillis(now),
+			usage.cycleDay ?? this.#defaultCycleDay,
+		) as number;
+		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 };
+	}
+
 	/** Flush unpersisted state immediately — the shutdown hook (bounds loss to ≤1 min). */
 	async flush(): Promise<void> {
 		if (this.#dirty) {

package/src/ports/forbidden-surface.test.ts

@@ -3,13 +3,22 @@
 // The single most safety-critical constraint in the package (Must-NOT-Have: "no MM
 // Simple.Connect / CreateBearer / Bearer.Connect calls ever"). Interfaces are
 // erased at runtime, so the enforcement is a source scan: every port `.ts` file is
-// stripped of comments (so prose mentions of "bearer" never trip it) and checked
-// for a method declaration whose name is `connect`, `simpleConnect`, or contains
-// "bearer". Adding such a method to any port fails this test — and therefore CI.
+// parsed with the TypeScript compiler API and each DECLARED member of an interface,
+// type literal, or class is checked for a name that is `connect`, `simpleConnect`,
+// or contains "bearer". Adding such a member to any port fails this test — and CI.
+//
+// The detector walks the real AST rather than the source text, so it catches shapes
+// a naive regex cannot: method signatures, property signatures typed as function
+// types, get/set accessors, optional members, and quoted or computed string-literal
+// member names (`'connect'()`, `['connect']()`) all resolve to their true name. It
+// only ever inspects member NAMES on those three declaration kinds — never string
+// literal values, value-position object-literal keys, comments, local variables, or
+// call expressions — so prose mentions of "bearer" and value keys never trip it.
 
 import { expect, test } from 'bun:test';
 import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import * as ts from 'typescript';
 
 const portsDir = import.meta.dir;
 
@@ -18,11 +27,82 @@ function isForbiddenMethodName(name: string): boolean {
 	return lower === 'connect' || lower === 'simpleconnect' || lower.includes('bearer');
 }
 
+/**
+ * Resolve a declared member's name node to its static string name, or `undefined`
+ * when the name is not statically knowable (e.g. a computed `[Symbol.iterator]` or a
+ * computed reference to a non-literal identifier). Plain identifiers, private names,
+ * string / numeric literals, and computed names wrapping a string / numeric literal
+ * (`['connect']`) all resolve to their real text.
+ */
+function resolveMemberName(name: ts.Node): string | undefined {
+	if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name)) {
+		return name.text;
+	}
+	if (ts.isStringLiteralLike(name) || ts.isNumericLiteral(name)) {
+		return name.text;
+	}
+	if (ts.isComputedPropertyName(name)) {
+		const { expression } = name;
+		if (ts.isStringLiteralLike(expression) || ts.isNumericLiteral(expression)) {
+			return expression.text;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Every DECLARED member name of an interface, type literal, or class in `source`,
+ * parsed via the TypeScript compiler API. Value-position object-literal keys, string
+ * literal values, comments, local variables, and call expressions are all excluded —
+ * only the port's actual type surface is inspected. Method signatures, property
+ * signatures (including arrow-typed properties), get/set accessors, optional members,
+ * and quoted / computed string-literal member names are all resolved to their name.
+ */
+function declaredMemberNames(source: string): string[] {
+	const sourceFile = ts.createSourceFile(
+		'port.ts',
+		source,
+		ts.ScriptTarget.Latest,
+		/* setParentNodes */ true,
+	);
+	const names: string[] = [];
+
+	const collectMembers = (members: readonly (ts.TypeElement | ts.ClassElement)[]): void => {
+		for (const member of members) {
+			if (member.name === undefined) {
+				continue;
+			}
+			const resolved = resolveMemberName(member.name);
+			if (resolved !== undefined) {
+				names.push(resolved);
+			}
+		}
+	};
+
+	const visit = (node: ts.Node): void => {
+		if (
+			ts.isInterfaceDeclaration(node) ||
+			ts.isClassDeclaration(node) ||
+			ts.isClassExpression(node) ||
+			ts.isTypeLiteralNode(node)
+		) {
+			collectMembers(node.members);
+		}
+		ts.forEachChild(node, visit);
+	};
+
+	visit(sourceFile);
+	return names;
+}
+
+// The retired regex detector — kept ONLY so the differential test below can prove,
+// by running it, that the AST rebuild is a strict improvement (it caught just one of
+// the seven forbidden shapes). Not used by any real-port scan; do not reintroduce.
 function stripComments(source: string): string {
 	return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
 }
 
-function declaredMemberNames(source: string): string[] {
+function legacyRegexMemberNames(source: string): string[] {
 	const names: string[] = [];
 	const methodDecl = /(?:^|\n)\s*([a-zA-Z_$][\w$]*)\s*[<(]/g;
 	let match = methodDecl.exec(source);
@@ -44,14 +124,14 @@ function portSourceFiles(): string[] {
 
 test('no port source declares a bearer / connect method', async () => {
 	for (const file of portSourceFiles()) {
-		const source = stripComments(await Bun.file(join(portsDir, file)).text());
+		const source = await Bun.file(join(portsDir, file)).text();
 		const forbidden = declaredMemberNames(source).filter(isForbiddenMethodName);
-		expect(forbidden, `forbidden method(s) in ${file}: ${forbidden.join(', ')}`).toEqual([]);
+		expect(forbidden, `forbidden member(s) in ${file}: ${forbidden.join(', ')}`).toEqual([]);
 	}
 });
 
 test('the ModemManager port source declares the expected non-bearer mutations', async () => {
-	const source = stripComments(await Bun.file(join(portsDir, 'modem-manager.ts')).text());
+	const source = await Bun.file(join(portsDir, 'modem-manager.ts')).text();
 	const names = declaredMemberNames(source);
 	for (const expected of [
 		'setRadioModes',
@@ -66,15 +146,96 @@ test('the ModemManager port source declares the expected non-bearer mutations',
 	}
 });
 
-test('the detector actually catches a bearer / connect method (self-test)', () => {
+test('the detector catches every forbidden member shape (self-test)', () => {
+	// Each line is a DISTINCT declaration shape the AST resolver must catch: a plain
+	// method, a computed string-literal method, a quoted string-literal method, an
+	// optional method, a get accessor, a set accessor, and an arrow-typed property.
+	// `setRadioModes` is a legitimate mutation that must pass through unflagged.
 	const rogue = `
-		export interface Rogue {
+		export interface RogueSurface {
 			connect(): Promise<void>;
-			createBearer(): Promise<void>;
-			bearerConnect(): Promise<void>;
+			['simpleConnect'](): void;
+			'createBearer'(): void;
+			bearerReset?(): void;
+			get bearerState(): number;
+			set bearerTarget(value: number);
+			bearerHook: () => Promise<void>;
+			setRadioModes(): Promise<void>;
+		}
+	`;
+	const flagged = declaredMemberNames(rogue).filter(isForbiddenMethodName).sort();
+	expect(flagged).toEqual([
+		'bearerHook',
+		'bearerReset',
+		'bearerState',
+		'bearerTarget',
+		'connect',
+		'createBearer',
+		'simpleConnect',
+	]);
+	// The acceptance bar for the rebuild: at least seven distinct forbidden shapes.
+	expect(flagged.length).toBeGreaterThanOrEqual(7);
+});
+
+test('the detector ignores string values, value-position keys, and non-forbidden members', () => {
+	// Three negative fixtures that must NOT trip the detector:
+	//   1. `reconnectPolicy` — a real interface member whose name merely CONTAINS the
+	//      substring "connect"; the predicate matches "connect" exactly, not as a
+	//      substring, so it must pass (proves the predicate is not overly broad).
+	//   2. `description: '…bearer…'` — a member whose string-literal VALUE contains
+	//      "bearer"; only member NAMES are inspected, never string content.
+	//   3. `bearerConnect: true` — a key in a value-position object literal, not a
+	//      type-level member declaration; the AST never walks object-literal keys.
+	const negative = `
+		interface LegitPort {
+			reconnectPolicy: RetryPolicy;
 			setRadioModes(): Promise<void>;
+			description: 'manages bearer state internally';
+		}
+		const runtimeConfig = {
+			bearerConnect: true,
+			description: 'manages bearer state internally',
+		};
+	`;
+	const members = declaredMemberNames(negative);
+	expect(members).toContain('reconnectPolicy');
+	expect(members).not.toContain('bearerConnect');
+	expect(members.filter(isForbiddenMethodName)).toEqual([]);
+});
+
+test('the AST detector catches member shapes the legacy regex missed (differential)', () => {
+	// The same rogue surface, run through BOTH detectors. The retired regex only ever
+	// matched an identifier immediately followed by `(` or `<` at a line start, so it
+	// caught the single plain method and missed the other six shapes. The AST walk
+	// catches all seven — the strict improvement the rebuild delivers.
+	const rogue = `
+		export interface RogueSurface {
+			connect(): Promise<void>;
+			['simpleConnect'](): void;
+			'createBearer'(): void;
+			bearerReset?(): void;
+			get bearerState(): number;
+			set bearerTarget(value: number);
+			bearerHook: () => Promise<void>;
 		}
 	`;
-	const flagged = declaredMemberNames(stripComments(rogue)).filter(isForbiddenMethodName).sort();
-	expect(flagged).toEqual(['bearerConnect', 'connect', 'createBearer']);
+	const legacyFlagged = legacyRegexMemberNames(stripComments(rogue))
+		.filter(isForbiddenMethodName)
+		.sort();
+	const astFlagged = declaredMemberNames(rogue).filter(isForbiddenMethodName).sort();
+
+	// The regex caught only the plain method.
+	expect(legacyFlagged).toEqual(['connect']);
+	// The AST catches every shape the regex missed, and then some.
+	for (const missed of [
+		'bearerHook',
+		'bearerReset',
+		'bearerState',
+		'bearerTarget',
+		'createBearer',
+		'simpleConnect',
+	]) {
+		expect(legacyFlagged).not.toContain(missed);
+		expect(astFlagged).toContain(missed);
+	}
 });

package/src/transport/calls.ts

@@ -0,0 +1,113 @@
+// Method-call dispatch and reply correlation for the D-Bus transport seam.
+//
+// A call marshals its body through the codec, registers a pending record so a bus drop can
+// reject it, and installs a per-call reply callback guarded by a `done` flag — so a reply
+// that arrives after the call already timed out or the connection dropped is silently
+// ignored rather than mis-correlated onto a stale promise. `rejectAll` mass-rejects every
+// in-flight call when the connection drops.
+
+import { decodeBody, encodeBody } from './codec';
+import { messageType, type RawBus, type RawMessage, type ReplyContext } from './dbus-native';
+import { DisconnectedError, TransportError } from './errors';
+import type { DbusValue, MethodCall, MethodReply } from './types';
+
+export const DEFAULT_CALL_TIMEOUT_MS = 30_000;
+
+interface PendingCall {
+	settle(): void;
+	reject(error: unknown): void;
+}
+
+export class CallDispatcher {
+	readonly #pending = new Set<PendingCall>();
+	readonly #callTimeoutMs: number;
+
+	constructor(callTimeoutMs: number) {
+		this.#callTimeoutMs = callTimeoutMs;
+	}
+
+	async call(bus: RawBus | null, connected: boolean, call: MethodCall): Promise<MethodReply> {
+		if (!connected || bus === null) {
+			throw new DisconnectedError('cannot call method: transport not connected');
+		}
+
+		const signature = call.signature ?? '';
+		const args = call.args ?? [];
+		const message: RawMessage = {
+			type: messageType.methodCall,
+			destination: call.destination,
+			path: call.path,
+			interface: call.interface,
+			member: call.member,
+		};
+		if (signature.length > 0) {
+			// Throws UnsupportedSignatureError / BigIntRequiredError before anything hits
+			// the wire.
+			message.signature = signature;
+			message.body = encodeBody(signature, args);
+		}
+
+		const timeoutMs = call.timeoutMs ?? this.#callTimeoutMs;
+		const pendingSet = this.#pending;
+		return new Promise<MethodReply>((resolve, reject) => {
+			let done = false;
+			const pending: PendingCall = {
+				settle: finish,
+				reject: (error) => {
+					finish();
+					reject(error);
+				},
+			};
+
+			function finish(): void {
+				if (done) {
+					return;
+				}
+				done = true;
+				clearTimeout(timer);
+				pendingSet.delete(pending);
+			}
+
+			const timer = setTimeout(() => {
+				finish();
+				reject(
+					new TransportError(
+						`Method call ${call.interface}.${call.member} timed out after ${timeoutMs}ms`,
+					),
+				);
+			}, timeoutMs);
+
+			pendingSet.add(pending);
+
+			bus.invoke(
+				message,
+				function reply(this: ReplyContext, error: unknown, ...body: unknown[]): void {
+					if (done) {
+						// Reply arrived after timeout/disconnect already settled the promise — ignore.
+						return;
+					}
+					finish();
+					if (error) {
+						reject(error instanceof Error ? error : new TransportError(String(error)));
+						return;
+					}
+					try {
+						const replySignature = this.signature ?? '';
+						const decoded: DbusValue[] =
+							replySignature.length > 0 ? decodeBody(replySignature, body) : [];
+						resolve({ signature: replySignature, body: decoded });
+					} catch (decodeError) {
+						reject(decodeError);
+					}
+				},
+			);
+		});
+	}
+
+	rejectAll(cause: unknown): void {
+		for (const pending of this.#pending) {
+			pending.reject(cause);
+		}
+		this.#pending.clear();
+	}
+}