@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/hardware/router-parsers.js

@@ -0,0 +1,234 @@
+import { z } from 'zod';
+import { parseHilinkXmlValue } from './hilink-protocol.js';
+export * from './hilink-protocol.js';
+const SIM_OBJECT_PATH = /^\/org\/freedesktop\/ModemManager1\/SIM\/\d+$/;
+/** The mmcli spelling of `MM_MODEM_STATE_FAILED_REASON_SIM_MISSING` — the ONLY proof of absence. */
+export const SIM_MISSING_FAILED_REASON = 'sim-missing';
+/** The fields a presence decision may be drawn from, in the order they are inspected. */
+export const SIM_PRESENCE_FIELDS = ['sim', 'simSlots', 'failedReason'];
+/** The presence decision together with the fact that produced it. */
+export function readSimPresence(facts) {
+    const sim = facts.sim?.trim() ?? '';
+    if (SIM_OBJECT_PATH.test(sim)) {
+        return { presence: 'present', evidence: { kind: 'sim-object-path', field: 'sim', value: sim } };
+    }
+    const slot = facts.simSlots
+        ?.map((each) => each.trim())
+        .find((each) => SIM_OBJECT_PATH.test(each));
+    if (slot !== undefined) {
+        return {
+            presence: 'present',
+            evidence: { kind: 'sim-slot-object-path', field: 'simSlots', value: slot },
+        };
+    }
+    if (facts.failedReason === SIM_MISSING_FAILED_REASON) {
+        return {
+            presence: 'absent',
+            evidence: {
+                kind: 'state-failed-reason',
+                field: 'failedReason',
+                value: SIM_MISSING_FAILED_REASON,
+            },
+        };
+    }
+    return { presence: 'unknown', evidence: { kind: 'no-evidence', inspected: SIM_PRESENCE_FIELDS } };
+}
+export function deriveSimPresence(facts) {
+    return readSimPresence(facts).presence;
+}
+const unknown = (reason) => ({
+    state: 'unknown',
+    reason,
+});
+const known = (value) => ({ state: 'known', value });
+function numericMetric(value) {
+    if (value === undefined || String(value).trim() === '')
+        return unknown('not-reported');
+    const parsed = Number.parseFloat(String(value));
+    return Number.isFinite(parsed) ? known(parsed) : unknown('malformed');
+}
+const flatRecordSchema = z.record(z.string(), z.union([z.string(), z.number()]));
+const ufiBodySchema = z.object({
+    reply: z.string(),
+    params: flatRecordSchema.optional(),
+});
+function parseFlatRecord(body) {
+    const parsed = z
+        .string()
+        .transform((value, context) => {
+        try {
+            return JSON.parse(value);
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                throw error;
+            context.addIssue({ code: 'custom', message: 'invalid JSON' });
+            return z.NEVER;
+        }
+    })
+        .pipe(flatRecordSchema)
+        .safeParse(body);
+    return parsed.success ? parsed.data : undefined;
+}
+function parseUfiBody(body) {
+    const parsed = z
+        .string()
+        .transform((value, context) => {
+        try {
+            return JSON.parse(value);
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                throw error;
+            context.addIssue({ code: 'custom', message: 'invalid JSON' });
+            return z.NEVER;
+        }
+    })
+        .pipe(ufiBodySchema)
+        .safeParse(body);
+    return parsed.success ? parsed.data : undefined;
+}
+export function parseHilinkSignal(input) {
+    const authStatus = parseHilinkXmlValue(input.status, 'code') === '125002';
+    const authSignal = parseHilinkXmlValue(input.signal, 'code') === '125002';
+    const statusReason = authStatus ? 'auth-expired' : 'not-reported';
+    const signalReason = authSignal ? 'auth-expired' : 'not-reported';
+    const metric = (tag) => authSignal ? unknown(signalReason) : numericMetric(parseHilinkXmlValue(input.signal, tag));
+    return {
+        provenance: 'hilink-admin-api',
+        freshness: authStatus && authSignal ? 'unknown' : 'live',
+        bars: authStatus
+            ? unknown(statusReason)
+            : numericMetric(parseHilinkXmlValue(input.status, 'SignalIcon')),
+        max_bars: authStatus
+            ? unknown(statusReason)
+            : numericMetric(parseHilinkXmlValue(input.status, 'maxsignal')),
+        dbm: metric('rssi'),
+        rsrp: metric('rsrp'),
+        rsrq: metric('rsrq'),
+        snr: unknown('unsupported'),
+        sinr: metric('sinr'),
+    };
+}
+export function parseZteSignal(body) {
+    const record = parseFlatRecord(body);
+    const malformed = record === undefined;
+    const metric = (key) => malformed ? unknown('malformed') : numericMetric(record[key]);
+    const bars = metric('signalbar');
+    return {
+        provenance: 'zte-goform',
+        freshness: malformed ? 'unknown' : 'live',
+        bars,
+        max_bars: bars.state === 'known' ? known(5) : unknown('not-reported'),
+        dbm: metric('rssi'),
+        rsrp: metric('lte_rsrp'),
+        rsrq: metric('lte_rsrq'),
+        snr: metric('lte_snr'),
+        sinr: unknown('unsupported'),
+    };
+}
+export function parseUfiSignal(input) {
+    const bodies = [input.sysinfo, input.overview, input.status].map(parseUfiBody);
+    const authExpired = bodies.every((body) => body?.reply === 'SessionOut');
+    const answered = bodies.some((body) => body?.reply === 'ok');
+    const value = bodies[0]?.params?.SIGNAL ?? bodies[1]?.params?.SIGNAL ?? bodies[2]?.params?.signalStrength;
+    const dbm = authExpired
+        ? unknown('auth-expired')
+        : answered
+            ? numericMetric(value)
+            : unknown('malformed');
+    return {
+        provenance: 'ufi-himiapi',
+        freshness: answered ? 'live' : 'unknown',
+        bars: unknown('unsupported'),
+        max_bars: unknown('unsupported'),
+        dbm,
+        rsrp: unknown('unsupported'),
+        rsrq: unknown('unsupported'),
+        snr: unknown('unsupported'),
+        sinr: unknown('unsupported'),
+    };
+}
+/**
+ * The vendor's own "unset" placeholders. A UFI answers `-` for a WAN address, an
+ * IMSI and an ICCID it does not have, and the ZTE builds answer `--` / `N/A` for
+ * an unpopulated counter — publishing any of those as a reading puts a value on
+ * screen that reads like a real one.
+ */
+const PLACEHOLDERS = new Set(['-', '--', 'n/a', 'N/A']);
+function stated(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = String(value).trim();
+    return normalized === '' || PLACEHOLDERS.has(normalized) ? undefined : normalized;
+}
+function compact(entries) {
+    const result = {};
+    for (const [key, value] of entries)
+        if (value !== undefined)
+            result[key] = value;
+    return Object.keys(result).length === 0 ? undefined : result;
+}
+export function parseZteDetails(body) {
+    const value = parseFlatRecord(body);
+    if (value === undefined)
+        return undefined;
+    return compact([
+        ['network_type', stated(value.network_type)],
+        [
+            'provider',
+            stated(value.network_provider_fullname) ??
+                stated(value.network_provider) ??
+                stated(value.provider),
+        ],
+        ['cell_id', stated(value.cell_id)],
+        ['roaming', stated(value.simcard_roam)],
+        ['mcc', stated(value.rmcc)],
+        ['mnc', stated(value.rmnc)],
+        ['pci', stated(value.lte_pci)],
+        // `band` and `network_band` are two DIFFERENT readings and must not be
+        // folded onto one key: `lte_band` is the serving cell's band, while
+        // `wan_active_band` is the band the WAN leg is active on, and the two
+        // disagree the moment carrier aggregation is up. Publishing either under
+        // the other's name reports a band the device never claimed for that leg.
+        ['band', stated(value.lte_band) ?? stated(value.band)],
+        ['network_band', stated(value.wan_active_band)],
+        ['carrier_aggregation', stated(value.wan_lte_ca)],
+        ['pcell_arfcn', stated(value.lte_ca_pcell_arfcn)],
+        ['pcell_band', stated(value.lte_ca_pcell_band)],
+        ['pcell_bandwidth', stated(value.lte_ca_pcell_bandwidth)],
+        ['scell_arfcn', stated(value.lte_ca_scell_arfcn)],
+        ['scell_band', stated(value.lte_ca_scell_band)],
+        ['scell_bandwidth', stated(value.lte_ca_scell_bandwidth)],
+        ['monthly_tx_bytes', stated(value.monthly_tx_bytes)],
+        ['monthly_rx_bytes', stated(value.monthly_rx_bytes)],
+        ['monthly_time', stated(value.monthly_time)],
+        ['monthly_period', stated(value.date_month)],
+        // Named `session_*` rather than `realtime_*`: these are cumulative counters
+        // and a throughput, and the vendor's own prefix reads as "live rate" for
+        // all five.
+        ['session_tx_bytes', stated(value.realtime_tx_bytes)],
+        ['session_rx_bytes', stated(value.realtime_rx_bytes)],
+        ['session_tx_rate', stated(value.realtime_tx_thrpt)],
+        ['session_rx_rate', stated(value.realtime_rx_thrpt)],
+        ['session_time', stated(value.realtime_time)],
+    ]);
+}
+export function parseUfiDetails(input) {
+    const overview = parseUfiBody(input.overview ?? '')?.params;
+    const sysinfo = parseUfiBody(input.sysinfo ?? '')?.params;
+    const product = parseUfiBody(input.produceInfo ?? '')?.params;
+    return compact([
+        ['product', stated(product?.productname) ?? stated(product?.ProductName)],
+        ['ssid', stated(overview?.SSID)],
+        ['wan_ip', stated(overview?.WANIP)],
+        ['imsi', stated(overview?.IMSI)],
+        ['iccid', stated(overview?.ICCID)],
+        ['web_version', stated(overview?.WEBVER)],
+        ['cell_id', stated(sysinfo?.cellid)],
+        ['station_id', stated(sysinfo?.bsid)],
+        ['cpu_temp', stated(sysinfo?.cputemp)],
+        ['wifi_clients', stated(sysinfo?.wifinum)],
+        ['eth_clients', stated(sysinfo?.ethnum)],
+    ]);
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export declare const PACKAGE_NAME = "@ceralive/modem-control";
+export * from './backend/index.js';
+export * from './band/index.js';
+export * from './capability/index.js';
+export * from './domain/index.js';
+export * from './fcc/index.js';
+export * from './hardware/router-parsers.js';
+export * from './journal/index.js';
+export * from './location/index.js';
+export * from './observations/index.js';
+export * from './operation-ids.js';
+export * from './operations/index.js';
+export * from './ports/index.js';
+export * from './providers/index.js';
+export * from './radio/index.js';
+export * from './redact.js';
+export * from './safety/index.js';
+export * from './sms/index.js';
+export * from './usb-mode/index.js';
+export * from './ussd/index.js';

package/dist/index.js

@@ -0,0 +1,27 @@
+// @ceralive/modem-control — package entry point.
+//
+// Phase A: the domain model (identity + orthogonal state + revisions) under
+// `./domain`, the MM / NM / Router port contracts + desired-state planner under
+// `./ports`, the redaction module (`./redact`), and the epoch-scoped ModemManager
+// D-Bus observer under `./backend`. The NetworkManager adapter, USB composition-mode
+// model, and data-usage sampler land in later waves.
+export const PACKAGE_NAME = '@ceralive/modem-control';
+export * from './backend/index.js';
+export * from './band/index.js';
+export * from './capability/index.js';
+export * from './domain/index.js';
+export * from './fcc/index.js';
+export * from './hardware/router-parsers.js';
+export * from './journal/index.js';
+export * from './location/index.js';
+export * from './observations/index.js';
+export * from './operation-ids.js';
+export * from './operations/index.js';
+export * from './ports/index.js';
+export * from './providers/index.js';
+export * from './radio/index.js';
+export * from './redact.js';
+export * from './safety/index.js';
+export * from './sms/index.js';
+export * from './usb-mode/index.js';
+export * from './ussd/index.js';

package/dist/journal/codec.d.ts

@@ -0,0 +1,44 @@
+import { type JournalEntry } from './entry.js';
+/** Why one record could not be read. `field` names the offending key, never its value. */
+export interface JournalDecodeFailure {
+    readonly code: 'empty' | 'invalid-json' | 'not-an-object' | 'unsupported-schema-version' | 'schema-mismatch' | 'unreadable';
+    readonly field?: string;
+    /** Byte offset for a JSON syntax error, when the runtime reported one. */
+    readonly offset?: number;
+}
+export type JournalDecodeResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly failure: JournalDecodeFailure;
+};
+declare function record(raw: unknown, field: string): Record<string, unknown>;
+declare function requiredString(source: Record<string, unknown>, field: string): string;
+declare function optionalString(source: Record<string, unknown>, field: string): string | undefined;
+declare function requiredNonNegativeInteger(source: Record<string, unknown>, field: string): number;
+declare function member<T extends string>(source: Record<string, unknown>, field: string, allowed: readonly T[]): T;
+/**
+ * Serialize one entry to a single line WITHOUT its terminator.
+ *
+ * Keys are emitted in a fixed order because the round-trip tests compare bytes,
+ * and byte comparison is the only assertion that catches a field a reader silently
+ * dropped (`JSON.parse` + a permissive validator will happily lose one and still
+ * report success — the same trap the srtla telemetry byte-parity suite exists for).
+ */
+export declare function encodeJournalEntry(entry: JournalEntry): string;
+/** Decode one line. An empty/whitespace-only line is reported, never silently dropped. */
+export declare function decodeJournalEntry(line: string): JournalDecodeResult<JournalEntry>;
+/** Decode an arbitrary JSON document with a caller-supplied validator. */
+export declare function decodeJournalDocument<T>(text: string, validate: (raw: unknown) => T): JournalDecodeResult<T>;
+/** The validator helpers the legacy reader reuses, so both shapes fail the same way. */
+export declare const journalSchema: {
+    readonly record: typeof record;
+    readonly requiredString: typeof requiredString;
+    readonly optionalString: typeof optionalString;
+    readonly requiredNonNegativeInteger: typeof requiredNonNegativeInteger;
+    readonly member: typeof member;
+    readonly schemaError: (field: string) => Error;
+    readonly schemaVersionError: () => Error;
+};
+export {};

package/dist/journal/codec.js

@@ -0,0 +1,198 @@
+// Line codec for the journal: exactly one entry per line, JSON, no wrapper.
+//
+// WHY DECODING RETURNS A RESULT INSTEAD OF THROWING. A journal is read at exactly
+// one moment — recovery after an unclean restart — and that is the moment a throw
+// is most expensive: it aborts the read at the first damaged byte and takes every
+// still-valid entry after it with it. The whole point of this module is that a
+// damaged record is DATA, reported alongside the records that survived, so nothing
+// earlier or later is discarded to make one bad line disappear.
+//
+// FAILURES NAME A FIELD, NEVER CONTENT. Same rule the two policy stores follow: a
+// classification carries the offending field name and a byte count, never the bytes
+// themselves, because a journal line can hold provider identifiers and refusal
+// reasons and a log line is the wrong place to reproduce them.
+import { MODEM_CONTROL_JOURNAL_SCHEMA_VERSION, } from './entry.js';
+class SchemaError extends Error {
+    field;
+    constructor(field) {
+        super(`schema-mismatch: ${field}`);
+        this.field = field;
+    }
+}
+class SchemaVersionError extends Error {
+    constructor() {
+        super('unsupported-schema-version');
+    }
+}
+function record(raw, field) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        throw new SchemaError(field);
+    return raw;
+}
+function requiredString(source, field) {
+    const value = source[field];
+    if (typeof value !== 'string' || value.length === 0)
+        throw new SchemaError(field);
+    return value;
+}
+function optionalString(source, field) {
+    const value = source[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new SchemaError(field);
+    return value;
+}
+function requiredNonNegativeInteger(source, field) {
+    const value = source[field];
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new SchemaError(field);
+    }
+    return value;
+}
+function requiredStringArray(source, field) {
+    const value = source[field];
+    if (!Array.isArray(value) || value.some((member) => typeof member !== 'string')) {
+        throw new SchemaError(field);
+    }
+    return value;
+}
+function member(source, field, allowed) {
+    const value = source[field];
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        throw new SchemaError(field);
+    }
+    return value;
+}
+const AUTHORITIES = ['provider', 'controller', 'hardware'];
+const IMPACTS = ['read', 'write', 'session', 'disruptive', 'recovery'];
+const CONFIDENCES = ['high', 'medium', 'low', 'unknown'];
+const UNKNOWN_OUTCOME_REASONS = [
+    'stale-generation',
+    'write-reply-timed-out',
+    'write-reply-dropped',
+];
+function parseDescriptor(raw) {
+    const source = record(raw, 'descriptor');
+    return {
+        descriptorId: requiredString(source, 'descriptorId'),
+        provider: requiredString(source, 'provider'),
+        authority: member(source, 'authority', AUTHORITIES),
+        mutationImpact: member(source, 'mutationImpact', IMPACTS),
+        profiles: requiredStringArray(source, 'profiles'),
+        firmware: requiredStringArray(source, 'firmware'),
+        confidence: member(source, 'confidence', CONFIDENCES),
+    };
+}
+function parseOutcome(raw) {
+    const source = record(raw, 'outcome');
+    switch (member(source, 'status', ['applied', 'refused', 'failed', 'unknown-outcome'])) {
+        case 'applied':
+            return { status: 'applied' };
+        case 'refused':
+            return { status: 'refused', reason: requiredString(source, 'reason') };
+        case 'failed':
+            return { status: 'failed', reason: requiredString(source, 'reason') };
+        case 'unknown-outcome':
+            return {
+                status: 'unknown-outcome',
+                reason: member(source, 'reason', UNKNOWN_OUTCOME_REASONS),
+            };
+    }
+}
+function parseEntry(raw) {
+    const source = record(raw, 'entry');
+    if (source.schemaVersion !== MODEM_CONTROL_JOURNAL_SCHEMA_VERSION)
+        throw new SchemaVersionError();
+    const base = {
+        schemaVersion: MODEM_CONTROL_JOURNAL_SCHEMA_VERSION,
+        operationId: requiredString(source, 'operationId'),
+        physicalModemId: requiredString(source, 'physicalModemId'),
+        generation: requiredNonNegativeInteger(source, 'generation'),
+        recordedAtMs: requiredNonNegativeInteger(source, 'recordedAtMs'),
+        descriptor: parseDescriptor(source.descriptor),
+    };
+    if (member(source, 'phase', ['started', 'completed']) === 'started') {
+        return { ...base, phase: 'started' };
+    }
+    return { ...base, phase: 'completed', outcome: parseOutcome(source.outcome) };
+}
+/** Classify a decode failure into a metadata-only result (never raw content). */
+function classify(error) {
+    if (error instanceof SchemaVersionError)
+        return { code: 'unsupported-schema-version' };
+    if (error instanceof SchemaError)
+        return { code: 'schema-mismatch', field: error.field };
+    if (error instanceof SyntaxError) {
+        const offset = /position (\d+)/.exec(error.message)?.[1];
+        return offset === undefined
+            ? { code: 'invalid-json' }
+            : { code: 'invalid-json', offset: Number(offset) };
+    }
+    return { code: 'unreadable' };
+}
+/**
+ * Serialize one entry to a single line WITHOUT its terminator.
+ *
+ * Keys are emitted in a fixed order because the round-trip tests compare bytes,
+ * and byte comparison is the only assertion that catches a field a reader silently
+ * dropped (`JSON.parse` + a permissive validator will happily lose one and still
+ * report success — the same trap the srtla telemetry byte-parity suite exists for).
+ */
+export function encodeJournalEntry(entry) {
+    const descriptor = {
+        descriptorId: entry.descriptor.descriptorId,
+        provider: entry.descriptor.provider,
+        authority: entry.descriptor.authority,
+        mutationImpact: entry.descriptor.mutationImpact,
+        profiles: entry.descriptor.profiles,
+        firmware: entry.descriptor.firmware,
+        confidence: entry.descriptor.confidence,
+    };
+    const base = {
+        schemaVersion: entry.schemaVersion,
+        phase: entry.phase,
+        operationId: entry.operationId,
+        physicalModemId: entry.physicalModemId,
+        generation: entry.generation,
+        recordedAtMs: entry.recordedAtMs,
+        descriptor,
+    };
+    return JSON.stringify(entry.phase === 'started' ? base : { ...base, outcome: entry.outcome });
+}
+/** Decode one line. An empty/whitespace-only line is reported, never silently dropped. */
+export function decodeJournalEntry(line) {
+    if (line.trim().length === 0)
+        return { ok: false, failure: { code: 'empty' } };
+    try {
+        return { ok: true, value: parseEntry(JSON.parse(line)) };
+    }
+    catch (error) {
+        return { ok: false, failure: classify(error) };
+    }
+}
+/** Decode an arbitrary JSON document with a caller-supplied validator. */
+export function decodeJournalDocument(text, validate) {
+    if (text.trim().length === 0)
+        return { ok: false, failure: { code: 'empty' } };
+    try {
+        return { ok: true, value: validate(JSON.parse(text)) };
+    }
+    catch (error) {
+        return { ok: false, failure: classify(error) };
+    }
+}
+/** The validator helpers the legacy reader reuses, so both shapes fail the same way. */
+export const journalSchema = {
+    record,
+    requiredString,
+    optionalString,
+    requiredNonNegativeInteger,
+    member,
+    schemaError(field) {
+        return new SchemaError(field);
+    },
+    schemaVersionError() {
+        return new SchemaVersionError();
+    },
+};

package/dist/journal/engine.d.ts

@@ -0,0 +1,28 @@
+import type { OperationJournalEvent, OperationJournalHook } from '../operations/contracts.js';
+import { type JournalRecovery } from './recovery.js';
+import type { JournalStore } from './store.js';
+export interface JournalEngineOptions {
+    /** The store — and therefore the path — is supplied by the composition root. */
+    readonly store: JournalStore;
+    readonly now?: () => number;
+}
+export declare class JournalEngine {
+    #private;
+    constructor(options: JournalEngineOptions);
+    /** Where this engine journals to; useful in a recovery log line. */
+    get path(): string;
+    /**
+     * The `OperationJournalHook` implementation.
+     *
+     * Generic per CALL rather than per instance, so one engine journals every
+     * descriptor in the process. A generic method satisfies the non-generic
+     * `OperationJournalHook<I, O>` member by instantiation, which is what lets an
+     * `OperationExecution` take the engine itself as its `journal`.
+     */
+    record<I, O>(event: OperationJournalEvent<I, O>): Promise<void>;
+    /** An explicitly typed hook, for a caller that prefers a narrow object. */
+    hook<I, O>(): OperationJournalHook<I, O>;
+    /** Read the journal back and reconstruct what was in flight. */
+    recover(): Promise<JournalRecovery>;
+}
+export declare function createJournalEngine(options: JournalEngineOptions): JournalEngine;

package/dist/journal/engine.js

@@ -0,0 +1,68 @@
+// The journal engine: the operation engine's journal hook, plus replay.
+//
+// `OperationExecution.journal` (todo 20's `OperationJournalHook`) is the seam the
+// operation engine already calls at `started` and at `completed`, and a descriptor
+// that declares `journal: { required: true }` is REFUSED outright when no hook is
+// supplied. This class is the durable implementation of that seam: it flattens the
+// event onto a journal entry and appends it, and it reads the same file back.
+//
+// THE ENGINE HOLDS NO PATH. It holds a `JournalStore`, and the store was handed a
+// path by whoever composed it. That is the same injection shape todo 19 used for
+// the ownership lock (`FlockResourceOwnershipOptions.lockPath` is REQUIRED and the
+// adapter substitutes nothing) and the same reason: an embedding process owns its
+// filesystem layout, and a library that guesses one is a library that writes to the
+// wrong disk on a device it has never seen.
+//
+// THE CLOCK IS INJECTED TOO. `now` defaults to `Date.now`, but a test that wants
+// deterministic timestamps supplies its own — the observation layer's rule that
+// this package never stamps data with a time it did not come from applies here as
+// well, and a replay assertion over timestamps must not be a race.
+import { journalDescriptorEvidence, journalOutcome } from './entry.js';
+import { reconstructJournalRecovery } from './recovery.js';
+export class JournalEngine {
+    #store;
+    #now;
+    constructor(options) {
+        this.#store = options.store;
+        this.#now = options.now ?? (() => Date.now());
+    }
+    /** Where this engine journals to; useful in a recovery log line. */
+    get path() {
+        return this.#store.path;
+    }
+    /**
+     * The `OperationJournalHook` implementation.
+     *
+     * Generic per CALL rather than per instance, so one engine journals every
+     * descriptor in the process. A generic method satisfies the non-generic
+     * `OperationJournalHook<I, O>` member by instantiation, which is what lets an
+     * `OperationExecution` take the engine itself as its `journal`.
+     */
+    record(event) {
+        return this.#store.append(entryFor(event, this.#now()));
+    }
+    /** An explicitly typed hook, for a caller that prefers a narrow object. */
+    hook() {
+        return { record: (event) => this.record(event) };
+    }
+    /** Read the journal back and reconstruct what was in flight. */
+    async recover() {
+        return reconstructJournalRecovery(await this.#store.read());
+    }
+}
+function entryFor(event, recordedAtMs) {
+    const base = {
+        schemaVersion: 1,
+        operationId: event.operationId,
+        physicalModemId: event.physicalModemId,
+        generation: event.generation,
+        recordedAtMs,
+        descriptor: journalDescriptorEvidence(event.descriptor),
+    };
+    return event.phase === 'started'
+        ? { ...base, phase: 'started' }
+        : { ...base, phase: 'completed', outcome: journalOutcome(event.result) };
+}
+export function createJournalEngine(options) {
+    return new JournalEngine(options);
+}