@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/sms/inbox-store.js

@@ -0,0 +1,82 @@
+// The inbox row store — folds `Added` / `Deleted` / resync events into one
+// newest-first, capped list.
+//
+// TWO PROPERTIES ARE THE WHOLE POINT OF THIS FILE, and both are failures a
+// signal-driven inbox produces on its own unless something stops them.
+//
+// DUPLICATE SUPPRESSION. ModemManager emits `Added` for a message it is
+// receiving AND again once it is stored, a re-subscribe after a bus hiccup can
+// replay one, and a consumer that also re-listed would hold the same message
+// twice. Rows are therefore keyed by object index and an `Added` carrying
+// nothing new is a NO-OP — `apply` answers `false` and no consumer is woken.
+//
+// RESTART RECOVERY. A source restart cannot be folded, because the events that
+// happened while it was down were never delivered. `resynced` therefore REPLACES
+// the whole row set rather than merging into it: merging would keep a message
+// deleted during the outage forever, and re-adding each row of a fresh list one
+// `added` at a time is exactly how a restart comes to duplicate the inbox it
+// already had.
+import { SMS_INBOX_CAP, sortAndCapSms } from './normalize.js';
+/** Two rows are the same message when every rendered field matches. */
+function sameMessage(a, b) {
+    return (a.id === b.id &&
+        a.text === b.text &&
+        a.state === b.state &&
+        a.from === b.from &&
+        a.timestamp === b.timestamp);
+}
+export function createSmsInboxStore(cap = SMS_INBOX_CAP) {
+    const rows = new Map();
+    const applyAdded = (message) => {
+        const held = rows.get(message.id);
+        // A repeated Added for a row we already hold VERBATIM is the duplicate
+        // this store exists to swallow. An Added that genuinely differs is a
+        // state transition (receiving -> received) and does update the row.
+        if (held !== undefined && sameMessage(held, message)) {
+            return false;
+        }
+        rows.set(message.id, message);
+        return true;
+    };
+    const applyResynced = (messages) => {
+        const next = new Map();
+        for (const message of messages) {
+            next.set(message.id, message);
+        }
+        // Report "unchanged" when the authoritative list matches what is already
+        // held, so a reconnect that found nothing new broadcasts nothing.
+        let changed = next.size !== rows.size;
+        if (!changed) {
+            for (const [id, message] of next) {
+                const held = rows.get(id);
+                if (held === undefined || !sameMessage(held, message)) {
+                    changed = true;
+                    break;
+                }
+            }
+        }
+        rows.clear();
+        for (const [id, message] of next) {
+            rows.set(id, message);
+        }
+        return changed;
+    };
+    return {
+        apply(event) {
+            switch (event.kind) {
+                case 'added':
+                    return applyAdded(event.message);
+                case 'deleted':
+                    return rows.delete(event.id);
+                case 'resynced':
+                    return applyResynced(event.messages);
+            }
+        },
+        snapshot() {
+            return sortAndCapSms([...rows.values()], cap);
+        },
+        size() {
+            return rows.size;
+        },
+    };
+}

package/dist/sms/index.d.ts

@@ -0,0 +1,4 @@
+export * from './dbus-messaging.js';
+export * from './inbox-store.js';
+export * from './mmcli-parse.js';
+export * from './normalize.js';

package/dist/sms/index.js

@@ -0,0 +1,10 @@
+// The read-only SMS surface: normalization, the `mmcli -K` grammar, the
+// Added/Deleted fold, and the ModemManager Messaging adapter.
+//
+// LIST / READ and observation ONLY. Nothing exported here composes, stores,
+// sends, or deletes a message; `readonly-gate.test.ts` fails the build if that
+// ever stops being true.
+export * from './dbus-messaging.js';
+export * from './inbox-store.js';
+export * from './mmcli-parse.js';
+export * from './normalize.js';

package/dist/sms/mmcli-parse.d.ts

@@ -0,0 +1,54 @@
+import type { SmsMessage, SmsReadRefusal } from '../ports/sms.js';
+/** A parse outcome. `detail` NEVER carries message content — key names only. */
+export type SmsParseResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly detail: string;
+};
+/**
+ * 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 declare function unescapeMmcliValue(value: string): string;
+/**
+ * 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 declare function parseSmsListOutput(raw: string): SmsParseResult<string[]>;
+/**
+ * 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 declare function parseSmsRecordOutput(raw: string): SmsParseResult<SmsMessage>;
+/**
+ * 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 declare function classifySmsFailure(description: string): SmsReadRefusal;

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';