@ceralive/modem-control 0.2.0 → 1.0.0

package/src/backend/usage/policy-write.ts

@@ -0,0 +1,207 @@
+// `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 type { DesiredUsage } from '../../domain';
+import {
+	isValidCycleDay,
+	isValidThresholdBytes,
+	type PersistedUsagePolicySlot,
+	selectUsagePolicy,
+	USAGE_POLICY_SCHEMA_VERSION,
+	type UsagePolicyStore,
+} from './policy-store';
+
+/**
+ * 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;
+	  };
+
+function validateRequest(request: SetUsagePolicyRequest): SetUsagePolicyRejection | undefined {
+	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: DesiredUsage, request: SetUsagePolicyRequest): DesiredUsage {
+	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: string, usage: DesiredUsage): PersistedUsagePolicySlot {
+	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: SetUsagePolicyDeps,
+	request: SetUsagePolicyRequest,
+): Promise<SetUsagePolicyResult> {
+	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: DesiredUsage;
+	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: Pick<SetUsagePolicyDeps, 'store' | 'now'>,
+	logicalSlotId: string,
+): Promise<DesiredUsage> {
+	const now = deps.now ?? Date.now;
+	const state = await deps.store.load(now());
+	return selectUsagePolicy(state, logicalSlotId);
+}

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/usb-mode/index.ts

@@ -1,8 +1,13 @@
-// The certified USB-mode catalog — schema, data, and lookups.
+// The certified USB-mode catalog — schema, data, lookups, and the evidence-bundle
+// ingestion seam.
 //
 // A6.1's bench CLI (`set-usb-mode`) and A6.2's `certify` tool both consume this: the
 // CLI looks up the permitted transition for a target mode, `certify` validates a
 // candidate entry against the schema before a human commits it.
+//
+// The ingestion seam (`./ingestion`, `./promotion-review`) is the documented path from a
+// captured `certify` bundle to a reviewed catalog commit — see `docs/CATALOG-INGESTION.md`.
+// It refuses a `synthetic: true` bundle for catalog promotion, by construction.
 
 export {
 	CERTIFIED_CATALOG,
@@ -25,3 +30,29 @@ export {
 	permittedTransitionSchema,
 	type SkuDiscriminator,
 } from './catalog-schema';
+export {
+	buildCatalogEntryCandidate,
+	buildClassifierFixture,
+	type CatalogClaim,
+	CLAIMABLE_CANONICAL_MODES,
+	type ClassifierFixture,
+	type EvidenceBundleView,
+	evidenceBundleViewSchema,
+	type FixtureProvenance,
+	type IngestionOutcome,
+	type IngestionRefusal,
+	type IngestionRefusalReason,
+	type IngestionRequest,
+	parseIngestionRequest,
+} from './ingestion';
+export {
+	type PromotionContext,
+	type PromotionRequest,
+	renderPromotionReview,
+} from './promotion-review';
+export {
+	type ParsedUsbDevice,
+	type ParsedUsbInterface,
+	parseUsbDevices,
+	selectUniqueDevice,
+} from './usb-devices-parse';