@ceralive/modem-control 0.2.0 → 1.0.0

package/src/backend/usage/index.ts

@@ -12,6 +12,29 @@ export {
 } from './accounting';
 export { clampCycleDay, cycleStart, daysInMonth } from './billing-cycle';
 export { readBootId } from './boot-id';
+export {
+	createUsagePolicyFileStore,
+	isValidCycleDay,
+	isValidThresholdBytes,
+	type PersistedUsagePolicy,
+	type PersistedUsagePolicySlot,
+	selectUsagePolicy,
+	USAGE_POLICY_SCHEMA_VERSION,
+	type UsagePolicyFileStoreOptions,
+	type UsagePolicyLogEvent,
+	type UsagePolicyLogger,
+	type UsagePolicyStore,
+} from './policy-store';
+export {
+	getUsagePolicy,
+	type SetUsagePolicyDeps,
+	type SetUsagePolicyRejection,
+	type SetUsagePolicyRequest,
+	type SetUsagePolicyResult,
+	setUsagePolicy,
+	type UsagePolicyApplication,
+	type UsagePolicyTarget,
+} from './policy-write';
 export {
 	type CounterSource,
 	parseProcNetDev,

package/src/backend/usage/policy-store.test.ts

@@ -0,0 +1,164 @@
+// Usage-policy persistence contract — mode 0600 (real fs.stat), fail-soft
+// corruption recovery with METADATA-ONLY logging, and the per-slot selector.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+	createUsagePolicyFileStore,
+	isValidCycleDay,
+	isValidThresholdBytes,
+	type PersistedUsagePolicy,
+	selectUsagePolicy,
+	USAGE_POLICY_SCHEMA_VERSION,
+	type UsagePolicyLogEvent,
+} from './policy-store';
+
+let dir: string;
+let path: string;
+
+beforeEach(async () => {
+	dir = await mkdtemp(join(tmpdir(), 'usage-policy-'));
+	path = join(dir, 'policy.json');
+});
+
+afterEach(async () => {
+	await rm(dir, { recursive: true, force: true });
+});
+
+const sample: PersistedUsagePolicy = {
+	schemaVersion: USAGE_POLICY_SCHEMA_VERSION,
+	savedAtMs: 1_700_000_000_000,
+	slots: [
+		{ logicalSlotId: 'slot-a', cycleDay: 15, thresholdBytes: 5_000_000_000 },
+		{ logicalSlotId: 'slot-b', cycleDay: 1 },
+		{ logicalSlotId: 'slot-c', thresholdBytes: 0 },
+	],
+};
+
+describe('UsagePolicyStore — versioned round-trip', () => {
+	test('save then load returns identical, schema-versioned state', async () => {
+		const store = createUsagePolicyFileStore({ path });
+		await store.save(sample);
+		expect(await store.load(1)).toEqual(sample);
+	});
+
+	test('an absent file loads as a fresh empty document and writes nothing', async () => {
+		const store = createUsagePolicyFileStore({ path });
+		const loaded = await store.load(4242);
+		expect(loaded).toEqual({
+			schemaVersion: USAGE_POLICY_SCHEMA_VERSION,
+			savedAtMs: 4242,
+			slots: [],
+		});
+		expect(readFile(path, 'utf8')).rejects.toThrow();
+	});
+
+	test('the written file is mode 0600 regardless of umask', async () => {
+		const store = createUsagePolicyFileStore({ path });
+		await store.save(sample);
+		expect((await stat(path)).mode & 0o777).toBe(0o600);
+	});
+});
+
+describe('UsagePolicyStore — fail-soft corruption', () => {
+	test('invalid JSON is replaced by a fresh 0600 file and logged as METADATA ONLY', async () => {
+		const events: UsagePolicyLogEvent[] = [];
+		await writeFile(path, '{"schemaVersion":1,"slots":');
+		const store = createUsagePolicyFileStore({ path, logger: (e) => events.push(e) });
+
+		const loaded = await store.load(7);
+
+		expect(loaded.slots).toEqual([]);
+		expect(events).toHaveLength(1);
+		expect(events[0]?.kind).toBe('corrupt-policy');
+		expect(events[0]?.reason).toContain('invalid-json');
+		expect((await stat(path)).mode & 0o777).toBe(0o600);
+	});
+
+	test.each([
+		[
+			'schemaVersion',
+			JSON.stringify({ ...sample, schemaVersion: 99 }),
+			'schema-mismatch: schemaVersion',
+		],
+		['savedAtMs', JSON.stringify({ ...sample, savedAtMs: 'soon' }), 'schema-mismatch: savedAtMs'],
+		['slots', JSON.stringify({ ...sample, slots: {} }), 'schema-mismatch: slots'],
+		[
+			'logicalSlotId',
+			JSON.stringify({ ...sample, slots: [{ cycleDay: 3 }] }),
+			'schema-mismatch: logicalSlotId',
+		],
+		[
+			'cycleDay',
+			JSON.stringify({ ...sample, slots: [{ logicalSlotId: 'a', cycleDay: 32 }] }),
+			'schema-mismatch: cycleDay',
+		],
+		[
+			'thresholdBytes',
+			JSON.stringify({ ...sample, slots: [{ logicalSlotId: 'a', thresholdBytes: -1 }] }),
+			'schema-mismatch: thresholdBytes',
+		],
+	])('a bad %s is rejected by name and never throws', async (_field, text, reason) => {
+		const events: UsagePolicyLogEvent[] = [];
+		await writeFile(path, text);
+		const store = createUsagePolicyFileStore({ path, logger: (e) => events.push(e) });
+
+		expect((await store.load(9)).slots).toEqual([]);
+		expect(events[0]?.reason).toBe(reason);
+	});
+
+	test('the corruption log carries a byte count and NEVER the file content', async () => {
+		const secretish = JSON.stringify({ schemaVersion: 1, slots: 'iccid-8991101200003204514' });
+		const events: UsagePolicyLogEvent[] = [];
+		await writeFile(path, secretish);
+		const store = createUsagePolicyFileStore({ path, logger: (e) => events.push(e) });
+
+		await store.load(11);
+
+		expect(events[0]?.bytes).toBe(Buffer.byteLength(secretish, 'utf8'));
+		expect(JSON.stringify(events[0])).not.toContain('8991101200003204514');
+	});
+});
+
+describe('selectUsagePolicy', () => {
+	test('returns the slot policy, omitting fields the slot never set', () => {
+		expect(selectUsagePolicy(sample, 'slot-a')).toEqual({
+			cycleDay: 15,
+			thresholdBytes: 5_000_000_000,
+		});
+		expect(selectUsagePolicy(sample, 'slot-b')).toEqual({ cycleDay: 1 });
+		expect(selectUsagePolicy(sample, 'slot-c')).toEqual({ thresholdBytes: 0 });
+	});
+
+	test('an unknown slot answers "no policy set", not a default', () => {
+		expect(selectUsagePolicy(sample, 'nope')).toEqual({});
+	});
+});
+
+describe('validators', () => {
+	test.each([
+		[1, true],
+		[31, true],
+		[15, true],
+		[0, false],
+		[32, false],
+		[1.5, false],
+		[Number.NaN, false],
+		['3', false],
+	])('isValidCycleDay(%p) === %p', (value, expected) => {
+		expect(isValidCycleDay(value)).toBe(expected);
+	});
+
+	test.each([
+		[0, true],
+		[5_000_000_000, true],
+		[-1, false],
+		[1.5, false],
+		[Number.POSITIVE_INFINITY, false],
+		['5', false],
+	])('isValidThresholdBytes(%p) === %p', (value, expected) => {
+		expect(isValidThresholdBytes(value)).toBe(expected);
+	});
+});

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

@@ -0,0 +1,216 @@
+// 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';
+import type { DesiredUsage } from '../../domain';
+
+/** The current on-disk schema version. Bump when the persisted shape changes. */
+export const USAGE_POLICY_SCHEMA_VERSION = 1;
+
+/** One slot's persisted usage policy. Both fields are absent when unset. */
+export interface PersistedUsagePolicySlot {
+	readonly logicalSlotId: string;
+	/** Day of month (1–31) the cycle resets; UTC, month-length clamped (A4.3). */
+	readonly cycleDay?: number;
+	/** Advisory threshold in bytes; crossing it raises an advisory, never gates. */
+	readonly thresholdBytes?: number;
+}
+
+/** The full persisted policy document. */
+export interface PersistedUsagePolicy {
+	readonly schemaVersion: typeof USAGE_POLICY_SCHEMA_VERSION;
+	readonly savedAtMs: number;
+	readonly slots: readonly PersistedUsagePolicySlot[];
+}
+
+/** A metadata-only log event. Corruption NEVER carries the raw file content. */
+export type UsagePolicyLogEvent = {
+	readonly kind: 'corrupt-policy';
+	readonly bytes: number;
+	readonly reason: string;
+};
+
+/** Sink for policy-store log events. Defaults to a metadata-only `console.warn`. */
+export type UsagePolicyLogger = (event: UsagePolicyLogEvent) => void;
+
+/** The persistence seam `setUsagePolicy` drives. */
+export interface UsagePolicyStore {
+	/** Load persisted policy; recreate a fresh 0600 file if absent or corrupt. */
+	load(nowMs: number): Promise<PersistedUsagePolicy>;
+	/** Atomically write policy with mode 0600 (temp → chmod → rename). */
+	save(state: PersistedUsagePolicy): Promise<void>;
+}
+
+export interface UsagePolicyFileStoreOptions {
+	readonly path: string;
+	readonly logger?: UsagePolicyLogger;
+}
+
+function defaultLogger(event: UsagePolicyLogEvent): void {
+	console.warn(`[usage-policy] ${event.kind}: bytes=${event.bytes} reason=${event.reason}`);
+}
+
+function freshState(nowMs: number): PersistedUsagePolicy {
+	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: string) {
+		super(`schema-mismatch: ${field}`);
+	}
+}
+
+/** True for a value that is a legal cycle day (integer 1–31). */
+export function isValidCycleDay(value: unknown): value is number {
+	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: unknown): value is number {
+	return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+
+function validateSlot(raw: unknown): PersistedUsagePolicySlot {
+	if (typeof raw !== 'object' || raw === null) {
+		throw new PolicySchemaError('slot');
+	}
+	const slot = raw as Record<string, unknown>;
+	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: unknown): PersistedUsagePolicy {
+	if (typeof raw !== 'object' || raw === null) {
+		throw new PolicySchemaError('document');
+	}
+	const doc = raw as Record<string, unknown>;
+	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: unknown): string {
+	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: PersistedUsagePolicy,
+	logicalSlotId: string,
+): DesiredUsage {
+	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: UsagePolicyFileStoreOptions): UsagePolicyStore {
+	const logger = options.logger ?? defaultLogger;
+	const { path } = options;
+
+	async function writeAtomic(state: PersistedUsagePolicy): Promise<void> {
+		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: number): Promise<PersistedUsagePolicy> {
+			let text: string;
+			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/src/backend/usage/policy-write.test.ts

@@ -0,0 +1,198 @@
+// `setUsagePolicy` contract — tri-state merge, typed refusals, persist-before-apply
+// ordering, and the live-sampler cycle-reset rule.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { DesiredUsage } from '../../domain';
+import {
+	createUsagePolicyFileStore,
+	type PersistedUsagePolicy,
+	selectUsagePolicy,
+	USAGE_POLICY_SCHEMA_VERSION,
+	type UsagePolicyStore,
+} from './policy-store';
+import { getUsagePolicy, setUsagePolicy, type UsagePolicyTarget } from './policy-write';
+
+let dir: string;
+let path: string;
+let store: UsagePolicyStore;
+
+const SLOT = 'slot-a';
+const NOW = 1_700_000_000_000;
+
+beforeEach(async () => {
+	dir = await mkdtemp(join(tmpdir(), 'usage-policy-write-'));
+	path = join(dir, 'policy.json');
+	store = createUsagePolicyFileStore({ path });
+});
+
+afterEach(async () => {
+	await rm(dir, { recursive: true, force: true });
+});
+
+function recordingSampler(): UsagePolicyTarget & {
+	calls: { slot: string; usage: DesiredUsage; at?: number }[];
+} {
+	const calls: { slot: string; usage: DesiredUsage; at?: number }[] = [];
+	return {
+		calls,
+		applyUsagePolicy(slot, usage, at) {
+			calls.push({ slot, usage, ...(at !== undefined ? { at } : {}) });
+			return { cycleStartMs: NOW, cycleReset: true };
+		},
+	};
+}
+
+describe('setUsagePolicy — persistence', () => {
+	test('writes a policy that reads back through getUsagePolicy', async () => {
+		const result = await setUsagePolicy(
+			{ store, now: () => NOW },
+			{ logicalSlotId: SLOT, cycleDay: 15, thresholdBytes: 5_000_000_000 },
+		);
+
+		expect(result.status).toBe('applied');
+		expect(await getUsagePolicy({ store }, SLOT)).toEqual({
+			cycleDay: 15,
+			thresholdBytes: 5_000_000_000,
+		});
+	});
+
+	test('an OMITTED field is left alone — a threshold write never drops the cycle day', async () => {
+		await setUsagePolicy({ store }, { logicalSlotId: SLOT, cycleDay: 9 });
+
+		await setUsagePolicy({ store }, { logicalSlotId: SLOT, thresholdBytes: 100 });
+
+		expect(await getUsagePolicy({ store }, SLOT)).toEqual({ cycleDay: 9, thresholdBytes: 100 });
+	});
+
+	test('an explicit null CLEARS that field and leaves the sibling standing', async () => {
+		await setUsagePolicy({ store }, { logicalSlotId: SLOT, cycleDay: 9, thresholdBytes: 100 });
+
+		await setUsagePolicy({ store }, { logicalSlotId: SLOT, cycleDay: null });
+
+		expect(await getUsagePolicy({ store }, SLOT)).toEqual({ thresholdBytes: 100 });
+	});
+
+	test('clearing BOTH fields removes the row rather than storing an empty one', async () => {
+		await setUsagePolicy({ store }, { logicalSlotId: SLOT, cycleDay: 9, thresholdBytes: 100 });
+
+		await setUsagePolicy({ store }, { logicalSlotId: SLOT, cycleDay: null, thresholdBytes: null });
+
+		expect((await store.load(NOW)).slots).toEqual([]);
+	});
+
+	test('a write to one slot never disturbs another', async () => {
+		await setUsagePolicy({ store }, { logicalSlotId: 'slot-a', cycleDay: 1 });
+		await setUsagePolicy({ store }, { logicalSlotId: 'slot-b', cycleDay: 20 });
+
+		await setUsagePolicy({ store }, { logicalSlotId: 'slot-a', cycleDay: 5 });
+
+		const state = await store.load(NOW);
+		expect(selectUsagePolicy(state, 'slot-a')).toEqual({ cycleDay: 5 });
+		expect(selectUsagePolicy(state, 'slot-b')).toEqual({ cycleDay: 20 });
+		expect(state.slots).toHaveLength(2);
+	});
+});
+
+describe('setUsagePolicy — typed refusals', () => {
+	test.each([
+		[{ logicalSlotId: '', cycleDay: 1 }, 'invalid-slot-id'],
+		[{ logicalSlotId: SLOT, cycleDay: 0 }, 'invalid-cycle-day'],
+		[{ logicalSlotId: SLOT, cycleDay: 32 }, 'invalid-cycle-day'],
+		[{ logicalSlotId: SLOT, cycleDay: 3.5 }, 'invalid-cycle-day'],
+		[{ logicalSlotId: SLOT, thresholdBytes: -1 }, 'invalid-threshold-bytes'],
+		[{ logicalSlotId: SLOT, thresholdBytes: 1.5 }, 'invalid-threshold-bytes'],
+	] as const)('%p is rejected as %s and writes nothing', async (request, reason) => {
+		const result = await setUsagePolicy({ store }, request);
+
+		expect(result).toMatchObject({ status: 'rejected', reason });
+		expect((await store.load(NOW)).slots).toEqual([]);
+	});
+
+	test('a refusal is returned, never thrown', async () => {
+		expect(setUsagePolicy({ store }, { logicalSlotId: SLOT, cycleDay: 99 })).resolves.toMatchObject(
+			{ status: 'rejected' },
+		);
+	});
+
+	test('a store that throws yields a typed failure and never reaches the sampler', async () => {
+		const sampler = recordingSampler();
+		const broken: UsagePolicyStore = {
+			load: async () => ({
+				schemaVersion: USAGE_POLICY_SCHEMA_VERSION,
+				savedAtMs: NOW,
+				slots: [],
+			}),
+			save: async () => {
+				throw new Error('disk full');
+			},
+		};
+
+		const result = await setUsagePolicy(
+			{ store: broken, sampler },
+			{ logicalSlotId: SLOT, cycleDay: 3 },
+		);
+
+		expect(result).toMatchObject({ status: 'failed', reason: 'disk full' });
+		expect(sampler.calls).toEqual([]);
+	});
+});
+
+describe('setUsagePolicy — live apply', () => {
+	test('the merged policy (not the raw request) reaches the sampler', async () => {
+		await setUsagePolicy({ store }, { logicalSlotId: SLOT, cycleDay: 9 });
+		const sampler = recordingSampler();
+
+		const result = await setUsagePolicy(
+			{ store, sampler, now: () => NOW },
+			{ logicalSlotId: SLOT, thresholdBytes: 250 },
+		);
+
+		expect(sampler.calls).toEqual([
+			{ slot: SLOT, usage: { cycleDay: 9, thresholdBytes: 250 }, at: NOW },
+		]);
+		expect(result).toMatchObject({ status: 'applied', applied: { cycleReset: true } });
+	});
+
+	test('with no sampler the write is persistence-only and reports no application', async () => {
+		const result = await setUsagePolicy({ store }, { logicalSlotId: SLOT, cycleDay: 2 });
+
+		expect(result).toEqual({ status: 'applied', logicalSlotId: SLOT, usage: { cycleDay: 2 } });
+	});
+
+	test('a sampler that throws is a typed failure AFTER the write already landed', async () => {
+		const result = await setUsagePolicy(
+			{
+				store,
+				sampler: {
+					applyUsagePolicy() {
+						throw new Error('sampler gone');
+					},
+				},
+			},
+			{ logicalSlotId: SLOT, cycleDay: 4 },
+		);
+
+		expect(result).toMatchObject({ status: 'failed', reason: 'sampler gone' });
+		expect(await getUsagePolicy({ store }, SLOT)).toEqual({ cycleDay: 4 });
+	});
+});
+
+describe('getUsagePolicy', () => {
+	test('an unwritten slot answers "no policy set"', async () => {
+		expect(await getUsagePolicy({ store }, 'never-written')).toEqual({});
+	});
+
+	test('reads a policy laid down by a previous process', async () => {
+		const seeded: PersistedUsagePolicy = {
+			schemaVersion: USAGE_POLICY_SCHEMA_VERSION,
+			savedAtMs: NOW,
+			slots: [{ logicalSlotId: SLOT, cycleDay: 28 }],
+		};
+		await store.save(seeded);
+
+		expect(await getUsagePolicy({ store }, SLOT)).toEqual({ cycleDay: 28 });
+	});
+});