@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/backend/transition-preconditions.d.ts

@@ -0,0 +1,101 @@
+import type { EpochMillis, IdentityConfidence } from '../domain/index.js';
+import type { ConnectionId, DeviceIfname } from '../ports/index.js';
+import { type CatalogEntry, type CertifiedCatalog, type MmUsbMode, type PermittedTransition, type RuntimeCompositionCapability, type RuntimeCompositionMode, type RuntimeCompositionVendor, type SkuDiscriminator } from '../usb-mode/index.js';
+import type { InterlockTarget, LifecycleInterlock } from './lifecycle-interlock.js';
+/** A held "transition active" interlock — released when the transaction ends. */
+export interface InterlockHold {
+    release(): Promise<void>;
+}
+/**
+ * The transition interlock. `canDisrupt` (from `LifecycleInterlock`) answers "is it
+ * safe to disrupt this modem now?"; `hold` marks a transition in progress so a
+ * streaming start is blocked for its duration. Both directions, one seam.
+ */
+export interface TransitionInterlock extends LifecycleInterlock {
+    hold(target: InterlockTarget): Promise<InterlockHold>;
+}
+/** The Phase-A interlock: always allows, holds nothing. */
+export declare const ALLOW_ALL_TRANSITION_INTERLOCK: TransitionInterlock;
+/** Live, re-evaluable readiness inputs — re-polled at entry AND in-actor. */
+export interface TransitionReadiness {
+    /** The identity confidence from A3.2's ladder; `'low'` refuses the transition. */
+    readonly identityConfidence: IdentityConfidence;
+}
+type UsbModeTransitionRequestBase = {
+    readonly stableKey: string;
+    readonly connectionId: ConnectionId;
+    readonly deviceIfname: DeviceIfname;
+    /** Physical-topology UID captured BEFORE the switch — survives re-enumeration. */
+    readonly cachedPhysicalUid: string;
+    /** The MM `Device` UID to inhibit by (cached — the modem disappears mid-switch). */
+    readonly inhibitUid: string;
+    /** Must be `true` (mirrors the CLI `--confirm` flag). */
+    readonly confirm: boolean;
+    /** Must be `true` (an extra maintenance-mode safety gate). */
+    readonly maintenance: boolean;
+    readonly now: EpochMillis;
+    /** Live readiness, re-polled at entry AND in-actor (TOCTOU-safe). */
+    probeReadiness(): Promise<TransitionReadiness>;
+};
+export type CatalogUsbModeTransitionRequest = UsbModeTransitionRequestBase & {
+    readonly strategy?: 'catalog';
+    readonly sku: SkuDiscriminator;
+    readonly fromMode: MmUsbMode;
+    readonly toMode: MmUsbMode;
+};
+export type RuntimeUsbModeTransitionRequest = UsbModeTransitionRequestBase & {
+    readonly strategy: 'runtime';
+    readonly vendor: RuntimeCompositionVendor;
+    readonly sku?: SkuDiscriminator;
+    readonly fromMode: RuntimeCompositionMode;
+    readonly toMode: RuntimeCompositionMode;
+    readonly capability: RuntimeCompositionCapability;
+};
+export type UsbModeTransitionRequest = CatalogUsbModeTransitionRequest | RuntimeUsbModeTransitionRequest;
+/** How a transition ended. */
+export type UsbModeTransitionOutcome = {
+    readonly status: 'refused';
+    readonly stage: 'entry' | 'in-actor';
+    readonly reason: string;
+    readonly steps: readonly string[];
+} | {
+    readonly status: 'succeeded';
+    readonly newIfname: DeviceIfname;
+    readonly steps: readonly string[];
+} | {
+    readonly status: 'failed';
+    readonly degraded: boolean;
+    readonly reason: string;
+    readonly steps: readonly string[];
+};
+export type UsbModeTransitionPlan = {
+    readonly atCommand: string;
+    readonly applyCommand?: string;
+    readonly proof: {
+        readonly tier: 'catalog-descriptors';
+        readonly transition: PermittedTransition;
+    } | {
+        readonly tier: 'runtime-requery';
+        readonly vendor: RuntimeCompositionVendor;
+        readonly target: RuntimeCompositionMode;
+        readonly currentQuery: string;
+    };
+};
+export type PreconditionResult = {
+    readonly ok: true;
+    readonly entry?: CatalogEntry;
+    readonly plan: UsbModeTransitionPlan;
+    readonly allowlistedCommands: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Check every transition precondition against the LIVE inputs. Called at entry and
+ * again in-actor; a request that passed at entry can fail here if the identity
+ * confidence dropped or the interlock closed in the meantime. Order is cheap-static
+ * checks first (confirm, maintenance, catalog, permitted) then the live probes
+ * (identity, interlock), so a refusal touches as little as possible.
+ */
+export declare function checkTransitionPreconditions(request: UsbModeTransitionRequest, catalog: CertifiedCatalog, interlock: TransitionInterlock): Promise<PreconditionResult>;
+export {};

package/dist/backend/transition-preconditions.js

@@ -0,0 +1,132 @@
+// USB-mode transition preconditions + the transition interlock seam.
+//
+// The preconditions gate a mode switch and are checked TWICE (draft §rounds 5/6
+// TOCTOU): once at transaction entry (so a doomed request never enters the actor) and
+// again INSIDE the actor (so a request that was valid at entry but became invalid
+// while queued is caught before any disruptive call). `checkTransitionPreconditions`
+// re-polls the LIVE inputs (`probeReadiness`, `interlock.canDisrupt`) each call, so
+// the two checks can genuinely disagree — that disagreement is the TIER-B race.
+//
+// The interlock is BIDIRECTIONAL: `canDisrupt` is the streaming→transition gate (may
+// I disrupt now?), inherited from A3.4's `LifecycleInterlock`; `hold` is the
+// transition→streaming gate (mark "transition active" until released). The Phase-A
+// stub allows both; Phase B wires CeraUI's streaming-admission check into the same
+// interface without changing the transaction.
+import { buildRuntimeCompositionSetCommand, findCatalogEntry, findPermittedTransition, RUNTIME_COMPOSITION_QUERY_REGISTRY, } from '../usb-mode/index.js';
+const NO_OP_HOLD = {
+    release() {
+        return Promise.resolve();
+    },
+};
+/** The Phase-A interlock: always allows, holds nothing. */
+export const ALLOW_ALL_TRANSITION_INTERLOCK = {
+    canDisrupt() {
+        return Promise.resolve({ allow: true });
+    },
+    hold() {
+        return Promise.resolve(NO_OP_HOLD);
+    },
+};
+function sameRuntimeMode(left, right) {
+    return Object.is(left, right);
+}
+function runtimePlan(request, catalog) {
+    const capability = request.capability;
+    if (capability.status !== 'available')
+        return { ok: false, reason: 'runtime capability unknown' };
+    if (!sameRuntimeMode(capability.current, request.fromMode))
+        return { ok: false, reason: 'runtime current mode changed' };
+    if (!capability.returnPathProven ||
+        !capability.offerable.some((mode) => sameRuntimeMode(mode, request.toMode)))
+        return { ok: false, reason: 'no-return-path' };
+    const atCommand = buildRuntimeCompositionSetCommand(request.vendor, request.toMode);
+    if (atCommand === undefined)
+        return { ok: false, reason: 'runtime target command unavailable' };
+    const entry = request.sku === undefined ? undefined : findCatalogEntry(catalog, request.sku);
+    if (entry !== undefined) {
+        const reviewed = entry.permittedTransitions.find((transition) => transition.atCommand === atCommand);
+        if (reviewed !== undefined) {
+            return {
+                ok: true,
+                entry,
+                plan: {
+                    atCommand: reviewed.atCommand,
+                    ...(reviewed.applyCommand === undefined ? {} : { applyCommand: reviewed.applyCommand }),
+                    proof: { tier: 'catalog-descriptors', transition: reviewed },
+                },
+                allowlistedCommands: entry.permittedTransitions.flatMap((transition) => transition.applyCommand === undefined
+                    ? [transition.atCommand]
+                    : [transition.atCommand, transition.applyCommand]),
+            };
+        }
+    }
+    return {
+        ok: true,
+        ...(entry === undefined ? {} : { entry }),
+        plan: {
+            atCommand,
+            proof: {
+                tier: 'runtime-requery',
+                vendor: request.vendor,
+                target: request.toMode,
+                currentQuery: RUNTIME_COMPOSITION_QUERY_REGISTRY[request.vendor].current,
+            },
+        },
+        allowlistedCommands: [atCommand],
+    };
+}
+/**
+ * Check every transition precondition against the LIVE inputs. Called at entry and
+ * again in-actor; a request that passed at entry can fail here if the identity
+ * confidence dropped or the interlock closed in the meantime. Order is cheap-static
+ * checks first (confirm, maintenance, catalog, permitted) then the live probes
+ * (identity, interlock), so a refusal touches as little as possible.
+ */
+export async function checkTransitionPreconditions(request, catalog, interlock) {
+    if (!request.confirm) {
+        return { ok: false, reason: 'confirm:true is required (missing --confirm)' };
+    }
+    if (!request.maintenance) {
+        return { ok: false, reason: 'maintenance flag is required' };
+    }
+    let staticResult;
+    if (request.strategy === 'runtime') {
+        staticResult = runtimePlan(request, catalog);
+    }
+    else {
+        const entry = findCatalogEntry(catalog, request.sku);
+        if (entry === undefined) {
+            return { ok: false, reason: `uncertified SKU ${request.sku.vidPid} ${request.sku.model}` };
+        }
+        const transition = findPermittedTransition(entry, request.fromMode, request.toMode);
+        if (transition === undefined) {
+            return {
+                ok: false,
+                reason: `transition ${request.fromMode}->${request.toMode} not permitted for ${request.sku.model}`,
+            };
+        }
+        staticResult = {
+            ok: true,
+            entry,
+            plan: {
+                atCommand: transition.atCommand,
+                ...(transition.applyCommand === undefined ? {} : { applyCommand: transition.applyCommand }),
+                proof: { tier: 'catalog-descriptors', transition },
+            },
+            allowlistedCommands: entry.permittedTransitions.flatMap((candidate) => candidate.applyCommand === undefined
+                ? [candidate.atCommand]
+                : [candidate.atCommand, candidate.applyCommand]),
+        };
+    }
+    if (!staticResult.ok)
+        return staticResult;
+    const readiness = await request.probeReadiness();
+    if (readiness.identityConfidence === 'low') {
+        return { ok: false, reason: 'low-confidence identity — refusing to transition' };
+    }
+    const verdict = await interlock.canDisrupt({ stableKey: request.stableKey });
+    if (!verdict.allow) {
+        return { ok: false, reason: `interlock held: ${verdict.reason}` };
+    }
+    return staticResult;
+}

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

@@ -0,0 +1,39 @@
+import type { IdentityConfidence, LogicalSlotId } from '../../domain/index.js';
+/** 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 declare function initialAccount(cycleStartMs: number): SlotAccount;
+/**
+ * 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 declare function applySample(prior: SlotAccount | undefined, input: SampleInput): SlotAccount;
+/** Convenience constructor for a `BaselineKey` from its parts. */
+export declare function baselineKey(logicalSlotId: LogicalSlotId, mappingGeneration: number, ifname: string, bootId: string): BaselineKey;

package/dist/backend/usage/accounting.js

@@ -0,0 +1,73 @@
+// 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.
+/** A fresh account for a slot first seen in `cycleStartMs`. */
+export function initialAccount(cycleStartMs) {
+    return { cycleBytes: 0, cycleStartMs, paused: false };
+}
+function sameKey(a, b) {
+    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, cycleStartMs) {
+    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, input) {
+    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, mappingGeneration, ifname, bootId) {
+    return { logicalSlotId, mappingGeneration, ifname, bootId };
+}

package/dist/backend/usage/billing-cycle.d.ts

@@ -0,0 +1,11 @@
+import type { EpochMillis } from '../../domain/index.js';
+/** Days in a given UTC month. `month` is 0-based (0 = January). Handles leap Feb. */
+export declare function daysInMonth(year: number, month: number): number;
+/** Clamp a requested cycle day to the last valid day of the given month. */
+export declare function clampCycleDay(cycleDay: number, year: number, month: number): number;
+/**
+ * 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 declare function cycleStart(now: EpochMillis, cycleDay: number): EpochMillis;

package/dist/backend/usage/billing-cycle.js

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

package/dist/backend/usage/boot-id.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Read the current kernel boot id (a UUID string). The path is injectable for tests;
+ * the default is the live `/proc` file. A read failure yields an empty string so the
+ * sampler still starts (baselines then simply never match a persisted session).
+ */
+export declare function readBootId(path?: string): Promise<string>;

package/{src/backend/usage/boot-id.ts → dist/backend/usage/boot-id.js}

@@ -3,16 +3,16 @@
 // `/proc/sys/kernel/random/boot_id` is a per-boot random UUID string. It changes on
 // every reboot, which is exactly when interface byte counters reset to zero, so the
 // sampler keys its baselines on it and re-baselines when it changes.
-
 /**
  * Read the current kernel boot id (a UUID string). The path is injectable for tests;
  * the default is the live `/proc` file. A read failure yields an empty string so the
  * sampler still starts (baselines then simply never match a persisted session).
  */
-export async function readBootId(path = '/proc/sys/kernel/random/boot_id'): Promise<string> {
-	try {
-		return (await Bun.file(path).text()).trim();
-	} catch {
-		return '';
-	}
+export async function readBootId(path = '/proc/sys/kernel/random/boot_id') {
+    try {
+        return (await Bun.file(path).text()).trim();
+    }
+    catch {
+        return '';
+    }
 }

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

@@ -0,0 +1,8 @@
+export { applySample, type BaselineKey, baselineKey, initialAccount, type SampleInput, type SlotAccount, } from './accounting.js';
+export { clampCycleDay, cycleStart, daysInMonth } from './billing-cycle.js';
+export { readBootId } from './boot-id.js';
+export { createUsagePolicyFileStore, isValidCycleDay, isValidThresholdBytes, type PersistedUsagePolicy, type PersistedUsagePolicySlot, selectUsagePolicy, USAGE_POLICY_SCHEMA_VERSION, type UsagePolicyFileStoreOptions, type UsagePolicyLogEvent, type UsagePolicyLogger, type UsagePolicyStore, } from './policy-store.js';
+export { getUsagePolicy, type SetUsagePolicyDeps, type SetUsagePolicyRejection, type SetUsagePolicyRequest, type SetUsagePolicyResult, setUsagePolicy, type UsagePolicyApplication, type UsagePolicyTarget, } from './policy-write.js';
+export { type CounterSource, parseProcNetDev, procNetDevCounterSource, } from './proc-net-dev.js';
+export { createUsageSampler, type SlotUsageSnapshot, type UsageObservation, UsageSampler, type UsageSamplerOptions, type UsageSnapshot, } from './sampler.js';
+export { createUsageFileStore, type PersistedSlot, type PersistedUsage, USAGE_SCHEMA_VERSION, type UsageFileStoreOptions, type UsageLogEvent, type UsageLogger, type UsageStore, } from './store.js';

package/dist/backend/usage/index.js

@@ -0,0 +1,11 @@
+// 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, baselineKey, initialAccount, } from './accounting.js';
+export { clampCycleDay, cycleStart, daysInMonth } from './billing-cycle.js';
+export { readBootId } from './boot-id.js';
+export { createUsagePolicyFileStore, isValidCycleDay, isValidThresholdBytes, selectUsagePolicy, USAGE_POLICY_SCHEMA_VERSION, } from './policy-store.js';
+export { getUsagePolicy, setUsagePolicy, } from './policy-write.js';
+export { parseProcNetDev, procNetDevCounterSource, } from './proc-net-dev.js';
+export { createUsageSampler, UsageSampler, } from './sampler.js';
+export { createUsageFileStore, USAGE_SCHEMA_VERSION, } from './store.js';

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

@@ -0,0 +1,50 @@
+import type { DesiredUsage } from '../../domain/index.js';
+/** The current on-disk schema version. Bump when the persisted shape changes. */
+export declare 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;
+}
+/** True for a value that is a legal cycle day (integer 1–31). */
+export declare function isValidCycleDay(value: unknown): value is number;
+/** True for a value that is a legal advisory threshold (non-negative integer). */
+export declare function isValidThresholdBytes(value: unknown): value is number;
+/**
+ * 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 declare function selectUsagePolicy(state: PersistedUsagePolicy, logicalSlotId: string): DesiredUsage;
+export declare function createUsagePolicyFileStore(options: UsagePolicyFileStoreOptions): UsagePolicyStore;