@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/sms/mmcli-parse.js

@@ -0,0 +1,224 @@
+// The `mmcli -K` SMS grammar.
+//
+// WHY A CLI GRAMMAR LIVES BESIDE A D-BUS PORT: `mmcli` is a client of the SAME
+// ModemManager daemon the D-Bus adapter talks to, and CeraUI has been reading
+// its inbox through it on real hardware since Phase A. Owning the grammar here
+// is what makes the port's output provable byte-for-byte against that reader on
+// the same captured output (`mmcli-parse.parity.test.ts`) — a claim no amount of
+// D-Bus-only code could support — and it is what lets a consumer move its
+// parsing onto this package without also having to move its transport in the
+// same change.
+//
+// CONTENT-FREE BY CONSTRUCTION. Unlike an ordinary parser, nothing here ever
+// puts a parsed LINE into an error, a log, or a receipt. A message body is
+// routinely a one-time code and a sender identifies the subscriber, so a
+// malformed record reports the KEY NAMES it found and nothing else — enough to
+// diagnose CLI drift, and carrying no message content. This module also never
+// logs at all, which is why it does not reuse a generic key/value splitter: the
+// generic one prints the offending line verbatim on any line it cannot split,
+// which would put message text into a log the first time mmcli reframed a body.
+import { normalizeSmsState, smsPathIndex } from './normalize.js';
+const fail = (reason, detail) => ({
+    ok: false,
+    reason,
+    detail,
+});
+const SMS_LIST_KEY = 'modem.messaging.sms';
+const LIST_LENGTH_SUFFIX = /\.length$/;
+const LIST_VALUE_SUFFIX = /\.value\[\d+]$/;
+const SMS_PATH_ANYWHERE_RE = /\/org\/freedesktop\/ModemManager1\/SMS\/(\d+)/;
+/**
+ * The escapes `g_strescape()` emits, minus the octal form. mmcli's `-K` writer
+ * runs EVERY value it prints through `g_strescape (value, NULL)`
+ * (`cli/mmcli-output.c`), so this table plus the 3-digit octal form is the
+ * complete grammar — anything else can be left untouched instead of guessed at.
+ */
+const SIMPLE_ESCAPES = {
+    b: 0x08,
+    f: 0x0c,
+    n: 0x0a,
+    r: 0x0d,
+    t: 0x09,
+    v: 0x0b,
+    '"': 0x22,
+    '\\': 0x5c,
+};
+/** Octal triplet first: `\302` is a byte, `\\302` is a backslash then "302". */
+const ESCAPE_RE = /\\(?:([0-7]{3})|([bfnrtv"\\]))/g;
+/**
+ * Undo `g_strescape()` on one `-K` value.
+ *
+ * mmcli does not print non-ASCII text — it prints the LITERAL ASCII characters
+ * of the octal escape. A Spanish message arrives on stdout as the eight
+ * characters `\`,`3`,`0`,`2`,`\`,`2`,`4`,`1` where the wire carried the two
+ * UTF-8 bytes `0xC2 0xA1` (confirmed on the bench board with `od -c`). The
+ * escapes are therefore per-BYTE, not per-character, and the only correct
+ * decode is to rebuild the byte sequence and read it back as UTF-8 — decoding
+ * each escape with `String.fromCharCode` instead turns `¡` into `¡`.
+ *
+ * Total and silent: it never throws and never logs, because the value it holds
+ * is message content. An escape outside the grammar is copied VERBATIM rather
+ * than dropped — mmcli cannot emit one, so meeting one means the value was
+ * never escaped and copying it is the only lossless answer.
+ */
+export function unescapeMmcliValue(value) {
+    if (!value.includes('\\')) {
+        return value;
+    }
+    const encoder = new TextEncoder();
+    const bytes = [];
+    const pushText = (text) => {
+        for (const byte of encoder.encode(text)) {
+            bytes.push(byte);
+        }
+    };
+    let cursor = 0;
+    ESCAPE_RE.lastIndex = 0;
+    let match = ESCAPE_RE.exec(value);
+    while (match !== null) {
+        if (match.index > cursor) {
+            pushText(value.slice(cursor, match.index));
+        }
+        const octal = match[1];
+        const simple = match[2];
+        if (octal !== undefined) {
+            bytes.push(Number.parseInt(octal, 8));
+        }
+        else if (simple !== undefined) {
+            const byte = SIMPLE_ESCAPES[simple];
+            if (byte !== undefined) {
+                bytes.push(byte);
+            }
+        }
+        cursor = match.index + match[0].length;
+        match = ESCAPE_RE.exec(value);
+    }
+    if (cursor < value.length) {
+        pushText(value.slice(cursor));
+    }
+    // A byte run that is not valid UTF-8 becomes U+FFFD — an honest
+    // "undecodable here" mark. Failing the whole read would lose every other
+    // field over one bad byte.
+    return new TextDecoder().decode(new Uint8Array(bytes));
+}
+/** Collect the `modem.messaging.sms` entries, honouring mmcli's array form. */
+function collectListEntries(raw) {
+    let scalar;
+    const array = [];
+    let sawArray = false;
+    for (const line of raw.split('\n')) {
+        const separator = line.indexOf(':');
+        if (separator <= 0) {
+            continue;
+        }
+        const key = line.slice(0, separator).trim();
+        // Unescaped AFTER the split, never before: a decoded byte must never be
+        // able to forge the `:` the line was split on.
+        const value = unescapeMmcliValue(line.slice(separator + 1).trim());
+        // mmcli renders an absent value as `--`; it carries no entry.
+        if (value === '--') {
+            continue;
+        }
+        if (key.replace(LIST_LENGTH_SUFFIX, '') === SMS_LIST_KEY && LIST_LENGTH_SUFFIX.test(key)) {
+            sawArray = true;
+        }
+        else if (key.replace(LIST_VALUE_SUFFIX, '') === SMS_LIST_KEY && LIST_VALUE_SUFFIX.test(key)) {
+            sawArray = true;
+            array.push(value);
+        }
+        else if (key === SMS_LIST_KEY) {
+            scalar = value;
+        }
+    }
+    if (sawArray) {
+        return array;
+    }
+    return scalar === undefined ? undefined : [scalar];
+}
+/**
+ * Extract SMS object paths from `mmcli -K -m <id> --messaging-list-sms`.
+ *
+ * An inbox with no messages prints as `modem.messaging.sms: --`, whose `--`
+ * carries no entry — so an ABSENT key is a legitimate EMPTY INBOX, exactly as it
+ * is for `--3gpp-scan`, not drift. What IS drift, and what fails loud here, is
+ * output that never mentions the key at all (a renamed field, an error body
+ * reaching this parser): answering "no messages" to a read that never ran would
+ * be the worst possible lie about an inbox.
+ */
+export function parseSmsListOutput(raw) {
+    const entries = collectListEntries(raw);
+    if (entries === undefined) {
+        if (!raw.includes(SMS_LIST_KEY)) {
+            return fail('no modem.messaging.sms key in the mmcli output', 'no-key');
+        }
+        return { ok: true, value: [] };
+    }
+    const paths = entries.filter((entry) => SMS_PATH_ANYWHERE_RE.test(entry));
+    if (entries.length > 0 && paths.length === 0) {
+        return fail('no SMS paths matched the ModemManager path grammar', 'no-path-match');
+    }
+    return { ok: true, value: paths };
+}
+/**
+ * Parse one `mmcli -K -s <path>` record.
+ *
+ * A malformed record reports the KEY NAMES it found and nothing else — see the
+ * content-free note at the top of this file.
+ */
+export function parseSmsRecordOutput(raw) {
+    const fields = new Map();
+    for (const line of raw.split('\n')) {
+        const separator = line.indexOf(':');
+        if (separator <= 0) {
+            continue;
+        }
+        const key = line.slice(0, separator).trim();
+        const value = line.slice(separator + 1).trim();
+        if (!key.startsWith('sms.') || value === '' || value === '--') {
+            continue;
+        }
+        fields.set(key, unescapeMmcliValue(value));
+    }
+    const keyNames = [...fields.keys()].join(', ');
+    const dbusPath = fields.get('sms.dbus-path');
+    if (dbusPath === undefined) {
+        return fail('no sms.dbus-path key in the mmcli output', keyNames);
+    }
+    const index = smsPathIndex(dbusPath);
+    if (Number.isNaN(index)) {
+        return fail('sms.dbus-path did not match the ModemManager path grammar', keyNames);
+    }
+    const from = fields.get('sms.content.number');
+    const timestamp = fields.get('sms.properties.timestamp');
+    return {
+        ok: true,
+        value: {
+            id: String(index),
+            ...(from !== undefined ? { from } : {}),
+            ...(timestamp !== undefined ? { timestamp } : {}),
+            // A data-only (WAP/PDU) message has no text at all; `''` says so honestly.
+            text: fields.get('sms.content.text') ?? '',
+            state: normalizeSmsState(fields.get('sms.properties.state')),
+        },
+    };
+}
+/**
+ * Classify a source failure into a refusal the operator can act on.
+ *
+ * The three recognised strings are ModemManager 1.24's own, confirmed on the
+ * bench board: a modem with no Messaging interface, a radio that has not come up
+ * yet, and a selector nothing answers to. Anything else stays `read_failed`
+ * rather than being guessed at.
+ */
+export function classifySmsFailure(description) {
+    if (/no messaging capabilities/i.test(description)) {
+        return 'unsupported';
+    }
+    if (/not enabled yet/i.test(description)) {
+        return 'not_enabled';
+    }
+    if (/couldn't find modem|cannot find modem/i.test(description)) {
+        return 'unknown_modem';
+    }
+    return 'read_failed';
+}

package/dist/sms/normalize.d.ts

@@ -0,0 +1,42 @@
+import type { SmsMessage, SmsState } from '../ports/sms.js';
+/**
+ * The read cap. The list is reduced to the highest-indexed paths BEFORE any
+ * per-message read, so a modem holding several hundred stored messages still
+ * costs at most this many reads.
+ */
+export declare const SMS_INBOX_CAP = 50;
+/**
+ * The SMS object-path grammar.
+ *
+ * It is a SEPARATE regex from the modem-path one on purpose: a ModemManager
+ * modem path is anchored on `/Modem/`, so reusing it here would refuse every
+ * real message (`/org/freedesktop/ModemManager1/SMS/36`) on the device.
+ */
+export declare const SMS_PATH_RE: RegExp;
+/** The trailing `/SMS/<n>` index, or `Number.NaN` when the path carries none. */
+export declare function smsPathIndex(path: string): number;
+/**
+ * Fold whatever the source called the state onto the known vocabulary. An
+ * unrecognised value becomes `unknown` rather than being passed through — the
+ * state is rendered to an operator, and a raw token nobody can act on is worse
+ * than an honest "we do not know".
+ */
+export declare function normalizeSmsState(raw: string | undefined): SmsState;
+export declare function smsTimestampEpoch(timestamp: string): number;
+/**
+ * Newest first, then capped.
+ *
+ * Sorted on the CARRIER timestamp because the object index is only a proxy for
+ * arrival order — ModemManager reuses freed indices, so a re-enumerated inbox
+ * can hand back a low index for the newest message. A message with no (or an
+ * unparseable) timestamp sorts LAST rather than first: promoting an undated
+ * message to the top of a "newest first" list would be a claim the device
+ * cannot support. Ties fall back to the index, descending.
+ */
+export declare function sortAndCapSms(messages: readonly SmsMessage[], cap?: number): SmsMessage[];
+/**
+ * Reduce a candidate path list to the paths worth reading: the highest-indexed
+ * {@link SMS_INBOX_CAP}, each of which must match the path grammar before it can
+ * reach a source as a selector.
+ */
+export declare function selectReadablePaths(paths: readonly string[], cap?: number): string[];

package/dist/sms/normalize.js

@@ -0,0 +1,95 @@
+// Device-agnostic SMS normalization — the rules that hold whichever source the
+// inbox was read through (ModemManager D-Bus or the `mmcli` client of the same
+// daemon).
+//
+// Every rule here is a PORT of a behaviour proven on the bench board through
+// CeraUI's `modules/modems/mmcli-sms.ts`, and each one exists because getting it
+// wrong is silent rather than loud. They are kept in one pure module so the
+// D-Bus adapter and the mmcli grammar cannot drift into two different answers
+// about the same inbox.
+/**
+ * The read cap. The list is reduced to the highest-indexed paths BEFORE any
+ * per-message read, so a modem holding several hundred stored messages still
+ * costs at most this many reads.
+ */
+export const SMS_INBOX_CAP = 50;
+/**
+ * The SMS object-path grammar.
+ *
+ * It is a SEPARATE regex from the modem-path one on purpose: a ModemManager
+ * modem path is anchored on `/Modem/`, so reusing it here would refuse every
+ * real message (`/org/freedesktop/ModemManager1/SMS/36`) on the device.
+ */
+export const SMS_PATH_RE = /^(?:\/org\/freedesktop\/ModemManager1\/SMS\/\d+|\d+)$/;
+const SMS_PATH_INDEX_RE = /\/org\/freedesktop\/ModemManager1\/SMS\/(\d+)/;
+const KNOWN_SMS_STATES = new Set([
+    'unknown',
+    'stored',
+    'receiving',
+    'received',
+    'sending',
+    'sent',
+]);
+/** The trailing `/SMS/<n>` index, or `Number.NaN` when the path carries none. */
+export function smsPathIndex(path) {
+    const match = path.match(SMS_PATH_INDEX_RE);
+    return match?.[1] === undefined ? Number.NaN : Number.parseInt(match[1], 10);
+}
+/**
+ * Fold whatever the source called the state onto the known vocabulary. An
+ * unrecognised value becomes `unknown` rather than being passed through — the
+ * state is rendered to an operator, and a raw token nobody can act on is worse
+ * than an honest "we do not know".
+ */
+export function normalizeSmsState(raw) {
+    return raw !== undefined && KNOWN_SMS_STATES.has(raw) ? raw : 'unknown';
+}
+/**
+ * ModemManager reports the service-centre timestamp with an HOURS-ONLY UTC
+ * offset — `2025-08-21T17:20:16-05`, captured verbatim from the bench board.
+ * That is not valid ISO 8601 and `Date.parse` answers NaN for it. Left
+ * unhandled, EVERY message scores as undated and "newest first" silently
+ * degrades to object-index order, which is the one ordering this module must
+ * not trust. The offset is widened to `-05:00`; the anchor requires a full
+ * `T??:??:??` time in front of it, so a bare `YYYY-MM-DD` is never mangled.
+ */
+const HOURS_ONLY_OFFSET_RE = /(T\d{2}:\d{2}:\d{2})([+-]\d{2})$/;
+export function smsTimestampEpoch(timestamp) {
+    const parsedTime = Date.parse(timestamp.replace(HOURS_ONLY_OFFSET_RE, '$1$2:00'));
+    return Number.isNaN(parsedTime) ? Number.NEGATIVE_INFINITY : parsedTime;
+}
+/**
+ * Newest first, then capped.
+ *
+ * Sorted on the CARRIER timestamp because the object index is only a proxy for
+ * arrival order — ModemManager reuses freed indices, so a re-enumerated inbox
+ * can hand back a low index for the newest message. A message with no (or an
+ * unparseable) timestamp sorts LAST rather than first: promoting an undated
+ * message to the top of a "newest first" list would be a claim the device
+ * cannot support. Ties fall back to the index, descending.
+ */
+export function sortAndCapSms(messages, cap = SMS_INBOX_CAP) {
+    const epoch = (message) => message.timestamp === undefined
+        ? Number.NEGATIVE_INFINITY
+        : smsTimestampEpoch(message.timestamp);
+    return [...messages]
+        .sort((a, b) => {
+        const delta = epoch(b) - epoch(a);
+        if (delta !== 0 && !Number.isNaN(delta)) {
+            return delta;
+        }
+        return Number(b.id) - Number(a.id);
+    })
+        .slice(0, cap);
+}
+/**
+ * Reduce a candidate path list to the paths worth reading: the highest-indexed
+ * {@link SMS_INBOX_CAP}, each of which must match the path grammar before it can
+ * reach a source as a selector.
+ */
+export function selectReadablePaths(paths, cap = SMS_INBOX_CAP) {
+    return [...paths]
+        .sort((a, b) => smsPathIndex(b) - smsPathIndex(a))
+        .slice(0, cap)
+        .filter((path) => SMS_PATH_RE.test(path));
+}

package/dist/testing/domain-fakes.d.ts

@@ -0,0 +1,58 @@
+import { type DeviceGeneration, type EpochMillis, type ObservationAuthority, type ObservationEnvelope, type OperationCompletion, type OperationConfidence, type OperationDescriptor, type OperationResult, type PhysicalModemId, type SourceEpoch, type StableKey } from '../domain/index.js';
+/**
+ * A canonical, valid `PhysicalModemId` for contract tests.
+ *
+ * It is built through the real constructor, so it can never be a value the domain
+ * refuses — an MM object path, an interface name, an IP address, an IMEI, or a
+ * subscriber identifier.
+ */
+export declare const FAKE_PHYSICAL_MODEM_ID: PhysicalModemId;
+/** The actor/storage key for {@link FAKE_PHYSICAL_MODEM_ID}. */
+export declare const FAKE_STABLE_KEY: StableKey;
+/** The generation every fake defaults to, so a consumer's fences have a stable anchor. */
+export declare const FAKE_GENERATION: DeviceGeneration;
+export type FakeObservationOptions = {
+    readonly stableKey?: StableKey;
+    readonly generation?: DeviceGeneration;
+    readonly source?: string;
+    readonly sourceEpoch?: SourceEpoch;
+    readonly observedAt?: EpochMillis;
+    readonly authority?: ObservationAuthority;
+};
+/** A fresh observation carrying `value`. */
+export declare function fakeFreshObservation<T>(value: T, options?: FakeObservationOptions): ObservationEnvelope<T>;
+/** A stale observation that RETAINS `value` — staleness never discards what was read. */
+export declare function fakeStaleObservation<T>(value: T, reason?: 'source-epoch-superseded' | 'ttl-expired' | 'source-degraded', options?: FakeObservationOptions): ObservationEnvelope<T>;
+/**
+ * An unavailable observation. It carries `value: null` by construction — there is no
+ * overload that lets a consumer's fake invent a value for data nobody could read.
+ */
+export declare function fakeUnavailableObservation<T>(reason?: 'source-unavailable' | 'device-absent' | 'provider-unavailable', options?: FakeObservationOptions): ObservationEnvelope<T>;
+export type FakeDescriptorOptions = {
+    readonly id?: string;
+    readonly provider?: string;
+    readonly authority?: 'provider' | 'controller' | 'hardware';
+    readonly confidence?: OperationConfidence;
+};
+/**
+ * A supported, auto-retryable idempotent READ descriptor.
+ *
+ * Routed through `defineOperationDescriptor`, so a fake that drifted into an
+ * unsupported/retryable combination throws instead of silently modelling a
+ * descriptor the domain would refuse.
+ */
+export declare function fakeReadDescriptor<O>(options?: FakeDescriptorOptions): OperationDescriptor<never, O>;
+/** A supported WRITE descriptor. Writes are never auto-retryable, so `retryClass` is `never`. */
+export declare function fakeWriteDescriptor<I, O>(options?: FakeDescriptorOptions): OperationDescriptor<I, O>;
+export type FakeOperationResultOptions = {
+    readonly operation?: 'read' | 'write';
+    readonly completionGeneration?: DeviceGeneration;
+    readonly currentGeneration?: DeviceGeneration;
+};
+/**
+ * Build an `OperationResult` by running the REAL classifier over a completion.
+ *
+ * A hand-written result literal is how a consumer's fake comes to disagree with the
+ * package about which completions require reconciliation; this cannot.
+ */
+export declare function fakeOperationResult<O>(completion: OperationCompletion<O>, options?: FakeOperationResultOptions): OperationResult<O>;

package/dist/testing/domain-fakes.js

@@ -0,0 +1,98 @@
+import { classifyOperationCompletion, defineOperationDescriptor, deviceGeneration, epochMillis, physicalModemId, sourceEpoch, stableKeyFromPhysicalModemId, } from '../domain/index.js';
+/**
+ * A canonical, valid `PhysicalModemId` for contract tests.
+ *
+ * It is built through the real constructor, so it can never be a value the domain
+ * refuses — an MM object path, an interface name, an IP address, an IMEI, or a
+ * subscriber identifier.
+ */
+export const FAKE_PHYSICAL_MODEM_ID = physicalModemId('serial:ceralive-contract-fake');
+/** The actor/storage key for {@link FAKE_PHYSICAL_MODEM_ID}. */
+export const FAKE_STABLE_KEY = stableKeyFromPhysicalModemId(FAKE_PHYSICAL_MODEM_ID);
+/** The generation every fake defaults to, so a consumer's fences have a stable anchor. */
+export const FAKE_GENERATION = deviceGeneration(1);
+function observationBase(options) {
+    return {
+        stableKey: options.stableKey ?? FAKE_STABLE_KEY,
+        generation: options.generation ?? FAKE_GENERATION,
+        source: options.source ?? 'contract-fake',
+        sourceEpoch: options.sourceEpoch ?? sourceEpoch(1),
+        observedAt: options.observedAt ?? epochMillis(1),
+        authority: options.authority ?? 'authoritative',
+    };
+}
+/** A fresh observation carrying `value`. */
+export function fakeFreshObservation(value, options = {}) {
+    return { ...observationBase(options), freshness: { state: 'fresh' }, value };
+}
+/** A stale observation that RETAINS `value` — staleness never discards what was read. */
+export function fakeStaleObservation(value, reason = 'ttl-expired', options = {}) {
+    const base = observationBase(options);
+    return {
+        ...base,
+        freshness: { state: 'stale', since: base.observedAt, reason },
+        value,
+    };
+}
+/**
+ * An unavailable observation. It carries `value: null` by construction — there is no
+ * overload that lets a consumer's fake invent a value for data nobody could read.
+ */
+export function fakeUnavailableObservation(reason = 'source-unavailable', options = {}) {
+    const base = observationBase(options);
+    return {
+        ...base,
+        freshness: { state: 'unavailable', since: base.observedAt, reason },
+        value: null,
+    };
+}
+function baseDescriptor(options, support, mutationImpact, retryClass) {
+    return defineOperationDescriptor({
+        id: options.id ?? 'contract-fake-operation',
+        support: {
+            read: support.read ? { supported: true } : { supported: false, reason: 'contract-fake' },
+            write: support.write ? { supported: true } : { supported: false, reason: 'contract-fake' },
+        },
+        authority: options.authority ?? 'provider',
+        provider: options.provider ?? 'contract-fake-provider',
+        constraints: { kind: 'unconstrained' },
+        livePreconditions: [],
+        availability: { state: 'available' },
+        mutationImpact,
+        retryClass,
+        readback: { required: false },
+        rollback: { required: false },
+        journal: { required: false },
+        admission: { required: false },
+        evidence: { profiles: [], firmware: [] },
+        confidence: options.confidence ?? 'medium',
+    });
+}
+/**
+ * A supported, auto-retryable idempotent READ descriptor.
+ *
+ * Routed through `defineOperationDescriptor`, so a fake that drifted into an
+ * unsupported/retryable combination throws instead of silently modelling a
+ * descriptor the domain would refuse.
+ */
+export function fakeReadDescriptor(options = {}) {
+    return baseDescriptor(options, { read: true, write: false }, 'read', 'idempotent-read');
+}
+/** A supported WRITE descriptor. Writes are never auto-retryable, so `retryClass` is `never`. */
+export function fakeWriteDescriptor(options = {}) {
+    return baseDescriptor(options, { read: true, write: true }, 'write', 'never');
+}
+/**
+ * Build an `OperationResult` by running the REAL classifier over a completion.
+ *
+ * A hand-written result literal is how a consumer's fake comes to disagree with the
+ * package about which completions require reconciliation; this cannot.
+ */
+export function fakeOperationResult(completion, options = {}) {
+    return classifyOperationCompletion({
+        operation: options.operation ?? 'write',
+        completionGeneration: options.completionGeneration ?? FAKE_GENERATION,
+        currentGeneration: options.currentGeneration ?? FAKE_GENERATION,
+        completion,
+    });
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './domain-fakes.js';
+export * from './provider-fakes.js';

package/dist/testing/index.js

@@ -0,0 +1,17 @@
+// `@ceralive/modem-control/testing` — the PUBLIC contract-fakes surface.
+//
+// A consumer testing against this package needs valid instances of the frozen v1.1
+// domain and provider contracts (`../domain`, `../providers`). Hand-rolling them is
+// how a consumer's fixtures come to disagree with the package: a hand-written
+// `OperationResult` literal quietly stops matching what `classifyOperationCompletion`
+// actually returns, and a hand-written envelope invents a value for an unavailable
+// read. Every fake here is built through the package's own constructors and
+// classifiers, so it cannot express a shape the domain refuses.
+//
+// This is NOT `control/test-support/`. That directory holds this repo's own heavy
+// internals — an MM-faithful fake D-Bus service on a private session bus and a
+// stateful `nmcli` harness. It lives outside `src`, is not published, and is not a
+// reusable public surface. This entry is pure data and functions: no bus, no daemon,
+// no process, no filesystem.
+export * from './domain-fakes.js';
+export * from './provider-fakes.js';

package/dist/testing/provider-fakes.d.ts

@@ -0,0 +1,45 @@
+import type { DeviceGeneration } from '../domain/index.js';
+import type { FingerprintResult, PassiveFact, ProviderDefinition, ProviderMatchRequest, ProviderOperationsSurface, ProviderTransport, UnauthenticatedProbe } from '../providers/index.js';
+/** The model string every provider fake matches on unless one is named. */
+export declare const FAKE_PROVIDER_MODEL = "contract-fake-model";
+export type FakeMatchRequestOptions = {
+    readonly generation?: DeviceGeneration;
+    readonly transport?: ProviderTransport;
+    readonly model?: string;
+    readonly composition?: string;
+    readonly firmware?: string;
+    readonly passiveFacts?: readonly PassiveFact[];
+};
+/** A well-formed `ProviderMatchRequest` whose passive facts name exactly one model. */
+export declare function fakeProviderMatchRequest(options?: FakeMatchRequestOptions): ProviderMatchRequest;
+export type FakeProviderOptions<TObservation> = {
+    readonly id?: string;
+    readonly profile?: string;
+    readonly profileVersion?: string;
+    readonly model?: string;
+    readonly eligibleTransports?: readonly ProviderTransport[];
+    readonly access?: ProviderOperationsSurface['access'];
+    readonly observation?: TObservation;
+    readonly probes?: readonly UnauthenticatedProbe[];
+};
+/**
+ * A minimal but COMPLETE `ProviderDefinition` — one strong required passive matcher on
+ * the model fact, no authenticated profile, no capability readers.
+ *
+ * It registers nothing and reaches no device: `observe` answers a fresh envelope built
+ * from the supplied observation, and `operations` returns the access surface asked for.
+ * This is the shape a consumer writes its own registry/matcher tests against without
+ * inventing a parallel provider contract.
+ */
+export declare function fakeProviderDefinition<TObservation>(options: FakeProviderOptions<TObservation> & {
+    readonly observation: TObservation;
+}): ProviderDefinition<TObservation, ProviderOperationsSurface>;
+export type FakeProbeOptions = {
+    readonly id?: string;
+    readonly signal?: FingerprintResult['signal'];
+    readonly strength?: FingerprintResult['strength'];
+    readonly profiles?: readonly string[];
+    readonly detail?: string;
+};
+/** A harmless unauthenticated probe that answers a fixed fingerprint. */
+export declare function fakeUnauthenticatedProbe(options?: FakeProbeOptions): UnauthenticatedProbe;

package/dist/testing/provider-fakes.js

@@ -0,0 +1,64 @@
+import { FAKE_GENERATION, FAKE_PHYSICAL_MODEM_ID, fakeFreshObservation } from './domain-fakes.js';
+/** The model string every provider fake matches on unless one is named. */
+export const FAKE_PROVIDER_MODEL = 'contract-fake-model';
+/** A well-formed `ProviderMatchRequest` whose passive facts name exactly one model. */
+export function fakeProviderMatchRequest(options = {}) {
+    const model = options.model ?? FAKE_PROVIDER_MODEL;
+    return {
+        physicalModemId: FAKE_PHYSICAL_MODEM_ID,
+        generation: options.generation ?? FAKE_GENERATION,
+        transport: options.transport ?? 'network',
+        passiveFacts: options.passiveFacts ?? [{ kind: 'model', value: model }],
+        composition: options.composition ?? 'ethernet-router',
+        firmware: options.firmware ?? '1.0.0',
+    };
+}
+/**
+ * A minimal but COMPLETE `ProviderDefinition` — one strong required passive matcher on
+ * the model fact, no authenticated profile, no capability readers.
+ *
+ * It registers nothing and reaches no device: `observe` answers a fresh envelope built
+ * from the supplied observation, and `operations` returns the access surface asked for.
+ * This is the shape a consumer writes its own registry/matcher tests against without
+ * inventing a parallel provider contract.
+ */
+export function fakeProviderDefinition(options) {
+    const id = options.id ?? 'contract-fake-provider';
+    const profile = options.profile ?? 'contract-fake-profile';
+    const model = options.model ?? FAKE_PROVIDER_MODEL;
+    const access = options.access ?? 'read-only';
+    const observation = options.observation;
+    return {
+        id,
+        profileVersion: options.profileVersion ?? '1.0.0',
+        eligibleTransports: options.eligibleTransports ?? ['network'],
+        passiveMatchers: [
+            {
+                id: `${id}-model`,
+                fact: 'model',
+                expected: [model],
+                profiles: [profile],
+                strength: 'strong',
+                required: true,
+            },
+        ],
+        unauthenticatedProbes: options.probes ?? [],
+        capabilityReaders: [],
+        observe: (_context) => Promise.resolve([fakeFreshObservation(observation, { source: id })]),
+        operations: (_profile) => ({ access }),
+        contractFixtures: [],
+    };
+}
+/** A harmless unauthenticated probe that answers a fixed fingerprint. */
+export function fakeUnauthenticatedProbe(options = {}) {
+    const result = {
+        signal: options.signal ?? 'match',
+        strength: options.strength ?? 'moderate',
+        profiles: options.profiles ?? ['contract-fake-profile'],
+        detail: options.detail ?? 'contract-fake probe',
+    };
+    return {
+        id: options.id ?? 'contract-fake-probe',
+        run: (_context) => Promise.resolve(result),
+    };
+}

package/dist/transport/calls.d.ts

@@ -0,0 +1,9 @@
+import { type RawBus } from './dbus-native.js';
+import type { MethodCall, MethodReply } from './types.js';
+export declare const DEFAULT_CALL_TIMEOUT_MS = 30000;
+export declare class CallDispatcher {
+    #private;
+    constructor(callTimeoutMs: number);
+    call(bus: RawBus | null, connected: boolean, call: MethodCall): Promise<MethodReply>;
+    rejectAll(cause: unknown): void;
+}