@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/journal/legacy-ceraui.js

@@ -0,0 +1,227 @@
+// COMPATIBILITY READ PATH for the mutation journal CeraUI already writes.
+//
+// WHY THIS EXISTS AT ALL. CeraUI has kept a durable modem-mutation journal since
+// long before this package had one, and devices in the field have those files on
+// disk right now. The two shapes are genuinely different — this package's journal
+// is an append-only EVENT LOG in one file, CeraUI's is a directory of per-modem
+// LATEST-STATE SNAPSHOTS, one JSON document per modem, rewritten whole on every
+// transition. Neither can be re-labelled into the other, so the bridge is a READER:
+// it decodes CeraUI's shape into the SAME `JournalOperationRecord` model
+// `recovery.ts` produces, so a consumer enumerates pending and unknown-outcome work
+// across both without CeraUI having to change its file format first.
+//
+// NOTHING HERE WRITES. This module reads and decodes; it never rewrites, repairs,
+// migrates in place, or deletes a slot. CeraUI's own reader leaves an unreadable
+// slot on disk deliberately, and a second reader that "cleaned up" behind it would
+// destroy the evidence CeraUI kept on purpose.
+//
+// THE DIRECTORY IS INJECTED, exactly like the native store's path — this module
+// hardcodes no location, and the path-injection gate covers it.
+//
+// THE SLOT FILENAME IS A HASH, and `legacyMutationSlotName` mirrors that rule so a
+// consumer can address ONE modem's slot without scanning. It is a RULE-D MIRROR of
+// CeraUI's helper, never a shared import — the same relationship the support-claim
+// ladder and the redaction key sets already have with their CeraUI twins.
+//
+// TWO MAPPING DECISIONS CARRY WEIGHT:
+//
+//  * `armed` maps to `pending` and `executing` maps to `unknown-outcome`. They are
+//    not the same fact. `armed` says the pre-state was captured and the write had
+//    not been dispatched, so the device is untouched. `executing` says the write
+//    WAS dispatched and no terminal state was ever recorded — which is precisely
+//    what this package calls an unknown outcome. Collapsing them would either
+//    invent certainty about a dispatched write or manufacture doubt about one that
+//    never left.
+//
+//  * `kind` is validated as a NON-EMPTY STRING, not against a frozen enum.
+//    CeraUI's runtime enum spreads its capability-module mutation kinds into the
+//    list, so the vocabulary grows on CeraUI's release cycle. Freezing a copy here
+//    would make this reader reject a perfectly valid file the day CeraUI adds a
+//    capability module — a compatibility reader that fails closed on new-but-valid
+//    input is worse than no reader at all.
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { decodeJournalDocument, journalSchema } from './codec.js';
+import { summarizeJournalRecords, } from './recovery.js';
+/** The `version` literal CeraUI's schema pins. */
+export const LEGACY_CERAUI_JOURNAL_VERSION = 1;
+/** CeraUI's cap on retained history entries per slot. */
+export const LEGACY_CERAUI_HISTORY_CAP = 32;
+export const LEGACY_CERAUI_MUTATION_STATES = [
+    'armed',
+    'executing',
+    'completed',
+    'failed',
+    'acknowledged',
+    'device-absent-quarantine',
+    'decommissioned',
+    'recommission-pending',
+];
+export const LEGACY_CERAUI_ACK_MODES = ['verified-rollback', 'force-rebaseline'];
+/**
+ * The slot filename CeraUI derives from a stable key.
+ *
+ * RULE-D MIRROR of CeraUI's own helper. It is a plain lowercase-hex SHA-256 of the
+ * key's UTF-8 bytes; the key itself never appears in the filename in plaintext.
+ */
+export function legacyMutationSlotName(stableKey) {
+    return createHash('sha256').update(stableKey, 'utf8').digest('hex');
+}
+function parseHistoryEntry(raw) {
+    const source = journalSchema.record(raw, 'history[]');
+    const detail = journalSchema.optionalString(source, 'detail');
+    return {
+        state: journalSchema.member(source, 'state', LEGACY_CERAUI_MUTATION_STATES),
+        at: journalSchema.requiredNonNegativeInteger(source, 'at'),
+        ...(detail === undefined ? {} : { detail }),
+    };
+}
+/** Validate one slot document. Throws the codec's metadata-only schema errors. */
+export function validateLegacyCeraUiEntry(raw) {
+    const source = journalSchema.record(raw, 'entry');
+    if (source.version !== LEGACY_CERAUI_JOURNAL_VERSION)
+        throw journalSchema.schemaVersionError();
+    const history = source.history;
+    if (!Array.isArray(history) || history.length > LEGACY_CERAUI_HISTORY_CAP) {
+        throw journalSchema.schemaError('history');
+    }
+    const detail = journalSchema.optionalString(source, 'detail');
+    const acknowledgedMode = source.acknowledgedMode === undefined
+        ? undefined
+        : journalSchema.member(source, 'acknowledgedMode', LEGACY_CERAUI_ACK_MODES);
+    return {
+        version: LEGACY_CERAUI_JOURNAL_VERSION,
+        stableKey: journalSchema.requiredString(source, 'stableKey'),
+        kind: journalSchema.requiredString(source, 'kind'),
+        state: journalSchema.member(source, 'state', LEGACY_CERAUI_MUTATION_STATES),
+        attemptId: journalSchema.requiredString(source, 'attemptId'),
+        startedAt: journalSchema.requiredNonNegativeInteger(source, 'startedAt'),
+        updatedAt: journalSchema.requiredNonNegativeInteger(source, 'updatedAt'),
+        preState: journalSchema.record(source.preState, 'preState'),
+        ...(detail === undefined ? {} : { detail }),
+        ...(acknowledgedMode === undefined ? {} : { acknowledgedMode }),
+        history: history.map(parseHistoryEntry),
+    };
+}
+/** Decode one slot document's text. Never throws; returns a typed failure. */
+export function decodeLegacyCeraUiEntry(text) {
+    return decodeJournalDocument(text, validateLegacyCeraUiEntry);
+}
+const DISPOSITION_BY_STATE = {
+    // Pre-state captured, write never dispatched: the device is untouched.
+    armed: 'pending',
+    // Dispatched with no terminal record — this package's `unknown-outcome`.
+    executing: 'unknown-outcome',
+    completed: 'resolved',
+    // CeraUI's replay keeps these on disk and refuses further mutations until an
+    // operator acknowledges. That is a KNOWN bad ending, not an unknown one.
+    failed: 'blocked',
+    acknowledged: 'resolved',
+    'device-absent-quarantine': 'blocked',
+    decommissioned: 'blocked',
+    'recommission-pending': 'blocked',
+};
+/**
+ * The descriptor evidence a legacy entry can honestly supply.
+ *
+ * CeraUI's journal predates `OperationDescriptor`, so there is no descriptor to
+ * flatten. Every field below is either a fact the file actually carries (the
+ * mutation kind) or an explicit statement that the file carries nothing:
+ * `confidence: 'unknown'` rather than a borrowed default, and empty evidence
+ * arrays rather than invented profiles. `mutationImpact: 'write'` is a fact, not a
+ * guess — CeraUI's file is a MUTATION journal and records nothing else.
+ */
+export function legacyDescriptorEvidence(kind) {
+    return {
+        descriptorId: kind,
+        provider: 'ceraui-legacy',
+        authority: 'controller',
+        mutationImpact: 'write',
+        profiles: [],
+        firmware: [],
+        confidence: 'unknown',
+    };
+}
+/** Project one decoded slot onto the shared recovery record model. */
+export function legacyOperationRecord(entry) {
+    const disposition = DISPOSITION_BY_STATE[entry.state];
+    return {
+        operationId: entry.attemptId,
+        // CeraUI's `stableKey`, NOT a `PhysicalModemId` — see the note on the field.
+        physicalModemId: entry.stableKey,
+        // CeraUI's journal has no device-generation fence; 0 records "unfenced"
+        // rather than claiming a generation the file never carried.
+        generation: 0,
+        descriptor: legacyDescriptorEvidence(entry.kind),
+        disposition,
+        origin: 'legacy-ceraui',
+        startedAtMs: entry.startedAt,
+        updatedAtMs: entry.updatedAt,
+        // One slot is one attempt; CeraUI rewrites the slot rather than appending.
+        attempts: 1,
+        // `outcome` is deliberately ABSENT for every legacy record, including the
+        // `unknown-outcome` one. `JournalOutcome`'s unknown reason union is the
+        // frozen domain vocabulary — `stale-generation` / `write-reply-timed-out` /
+        // `write-reply-dropped` — and CeraUI's `executing` state asserts none of
+        // them: it says a write was dispatched and never concluded, not why. Naming
+        // one anyway would be the invented reading this package refuses everywhere
+        // else. The disposition carries the fact; the reason stays unclaimed.
+    };
+}
+/**
+ * Read a whole CeraUI journal directory.
+ *
+ * An unreadable or non-conforming slot is reported as damage and LEFT IN PLACE;
+ * every readable slot still comes back. That is the same non-truncating contract
+ * the native store makes, applied to a directory instead of a file.
+ */
+export async function readLegacyCeraUiJournal(options) {
+    let names;
+    try {
+        names = await readdir(options.dir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { recovery: summarizeJournalRecords([], []), entries: [] };
+        }
+        return {
+            recovery: summarizeJournalRecords([], [{ location: { kind: 'file' }, bytes: 0, failure: { code: 'unreadable' } }]),
+            entries: [],
+        };
+    }
+    const entries = [];
+    const damage = [];
+    // Sorted so a recovery report is stable across filesystems that do not order
+    // `readdir`; the slot names are hashes, so the order carries no other meaning.
+    for (const name of [...names].sort()) {
+        if (!name.endsWith('.json'))
+            continue;
+        let text;
+        try {
+            text = await readFile(join(options.dir, name), 'utf8');
+        }
+        catch {
+            damage.push({
+                location: { kind: 'slot', slot: name },
+                bytes: 0,
+                failure: { code: 'unreadable' },
+            });
+            continue;
+        }
+        const decoded = decodeLegacyCeraUiEntry(text);
+        if (decoded.ok) {
+            entries.push(decoded.value);
+            continue;
+        }
+        damage.push({
+            location: { kind: 'slot', slot: name },
+            bytes: Buffer.byteLength(text, 'utf8'),
+            failure: decoded.failure,
+        });
+    }
+    return {
+        recovery: summarizeJournalRecords(entries.map(legacyOperationRecord), damage),
+        entries,
+    };
+}

package/dist/journal/recovery.d.ts

@@ -0,0 +1,58 @@
+import { DomainError } from '../domain/index.js';
+import type { JournalDescriptorEvidence, JournalOutcome } from './entry.js';
+import type { JournalDamageRecord, JournalReadResult } from './store.js';
+export type JournalRecoveryDisposition = 'pending' | 'unknown-outcome' | 'resolved' | 'blocked';
+/** Where a record came from. Also tells a consumer how to read `physicalModemId`. */
+export type JournalRecordOrigin = 'native' | 'legacy-ceraui';
+/**
+ * One operation reconstructed from the journal.
+ *
+ * `physicalModemId` is TEXT, not the branded `PhysicalModemId`, and that is
+ * deliberate: for a `legacy-ceraui` record it holds CeraUI's own `stableKey`,
+ * which is a different identity vocabulary and would be REFUSED by
+ * `physicalModemId()`'s constructor. Coercing it would either throw on a
+ * perfectly valid legacy file or launder a foreign identity into a branded type
+ * that promises it came from the serial / ID_PATH ladder. `origin` is what tells
+ * a consumer which vocabulary it is holding.
+ */
+export interface JournalOperationRecord {
+    readonly operationId: string;
+    readonly physicalModemId: string;
+    readonly generation: number;
+    readonly descriptor: JournalDescriptorEvidence;
+    readonly disposition: JournalRecoveryDisposition;
+    readonly origin: JournalRecordOrigin;
+    readonly startedAtMs: number;
+    readonly updatedAtMs: number;
+    readonly attempts: number;
+    readonly outcome?: JournalOutcome;
+}
+export interface JournalRecovery {
+    /** Every reconstructed operation, in first-appearance order. */
+    readonly records: readonly JournalOperationRecord[];
+    readonly pending: readonly JournalOperationRecord[];
+    readonly unknownOutcome: readonly JournalOperationRecord[];
+    readonly blocked: readonly JournalOperationRecord[];
+    /** Distinct modem identities that must be reconciled before the next mutation. */
+    readonly reconciliationRequired: readonly string[];
+    readonly damage: readonly JournalDamageRecord[];
+}
+/** Raised only by `assertJournalIntact`; recovery itself always returns a report. */
+export declare class JournalRecoveryError extends DomainError {
+    readonly name = "JournalRecoveryError";
+    readonly damage: readonly JournalDamageRecord[];
+    constructor(damage: readonly JournalDamageRecord[]);
+}
+/**
+ * Escalate a damaged journal to a throw, for a caller that wants fail-closed.
+ *
+ * Kept SEPARATE from `reconstructJournalRecovery` on purpose: recovery must be
+ * able to hand back the survivors even when part of the file is unreadable, so
+ * the decision to refuse to proceed belongs to the caller, after it has seen
+ * what did survive.
+ */
+export declare function assertJournalIntact(recovery: JournalRecovery): void;
+/** Fold decoded entries into per-operation records. Pure; no clock, no I/O. */
+export declare function reconstructJournalRecovery(read: JournalReadResult): JournalRecovery;
+/** Build the summary views over already-reconstructed records (native or legacy). */
+export declare function summarizeJournalRecords(records: readonly JournalOperationRecord[], damage: readonly JournalDamageRecord[]): JournalRecovery;

package/dist/journal/recovery.js

@@ -0,0 +1,117 @@
+// Replay: fold a journal back into "what was in flight when we died".
+//
+// This is the whole reason the journal exists. `operations/operation-engine.ts`
+// keeps its uncertainty fence in a `Set<PhysicalModemId>` on the engine instance,
+// so a process death drops it and the next mutation proceeds as if nothing were
+// outstanding. Folding the journal reconstructs that set from disk.
+//
+// THE FOLD IS ORDER-SENSITIVE AND LAST-WRITE-WINS PER OPERATION. Entries are
+// applied in file order, keyed by (physical modem, operation id, generation). A
+// second `started` on a live key is a re-run and re-opens the record rather than
+// being deduplicated away — the journal records attempts, and hiding a second
+// attempt would make a retry loop invisible in exactly the forensics the file is
+// kept for.
+//
+// FOUR DISPOSITIONS, AND TWO OF THEM MEAN "RECONCILE BEFORE MUTATING AGAIN":
+//
+//   pending          a start with no completion — the process died inside the
+//                    operation, so whether the device changed is unknown.
+//   unknown-outcome  a completion the engine itself classified unknown: a stale
+//                    generation, or a write reply that timed out or was dropped.
+//   resolved         a definite ending (applied / refused / failed). The engine
+//                    treats a definite failure as definite; so does this.
+//   blocked          a terminal state a human must clear. Native journals never
+//                    produce it today — it exists because CeraUI's own mutation
+//                    journal HAS such states (`failed`, quarantine, decommission)
+//                    and `legacy-ceraui.ts` maps onto this same model. Folding
+//                    those into `resolved` would report an operator-blocked device
+//                    as healthy; folding them into `unknown-outcome` would claim
+//                    uncertainty about an outcome that is actually known.
+//
+// `reconciliationRequired` deliberately covers `pending` + `unknown-outcome` only.
+// A blocked record is a KNOWN bad ending awaiting acknowledgement, and answering
+// it with a reconciliation pass would silently clear a state that exists precisely
+// so it cannot be cleared silently.
+import { DomainError } from '../domain/index.js';
+/** Raised only by `assertJournalIntact`; recovery itself always returns a report. */
+export class JournalRecoveryError extends DomainError {
+    name = 'JournalRecoveryError';
+    damage;
+    constructor(damage) {
+        super(`journal recovery found ${damage.length} damaged record(s)`);
+        this.damage = damage;
+    }
+}
+/**
+ * Escalate a damaged journal to a throw, for a caller that wants fail-closed.
+ *
+ * Kept SEPARATE from `reconstructJournalRecovery` on purpose: recovery must be
+ * able to hand back the survivors even when part of the file is unreadable, so
+ * the decision to refuse to proceed belongs to the caller, after it has seen
+ * what did survive.
+ */
+export function assertJournalIntact(recovery) {
+    if (recovery.damage.length > 0)
+        throw new JournalRecoveryError(recovery.damage);
+}
+function keyOf(entry) {
+    return `${entry.physicalModemId}\u0000${entry.operationId}\u0000${entry.generation}`;
+}
+function dispositionOf(outcome) {
+    return outcome.status === 'unknown-outcome' ? 'unknown-outcome' : 'resolved';
+}
+/** Fold decoded entries into per-operation records. Pure; no clock, no I/O. */
+export function reconstructJournalRecovery(read) {
+    const byKey = new Map();
+    const order = [];
+    for (const { entry } of read.entries) {
+        const key = keyOf(entry);
+        const previous = byKey.get(key);
+        if (previous === undefined)
+            order.push(key);
+        if (entry.phase === 'started') {
+            byKey.set(key, {
+                operationId: entry.operationId,
+                physicalModemId: entry.physicalModemId,
+                generation: entry.generation,
+                descriptor: entry.descriptor,
+                disposition: 'pending',
+                origin: 'native',
+                // The FIRST start is when this operation began; a re-run does not
+                // rewrite history, it increments the attempt count.
+                startedAtMs: previous?.startedAtMs ?? entry.recordedAtMs,
+                updatedAtMs: entry.recordedAtMs,
+                attempts: (previous?.attempts ?? 0) + 1,
+            });
+            continue;
+        }
+        byKey.set(key, {
+            operationId: entry.operationId,
+            physicalModemId: entry.physicalModemId,
+            generation: entry.generation,
+            descriptor: entry.descriptor,
+            disposition: dispositionOf(entry.outcome),
+            origin: 'native',
+            startedAtMs: previous?.startedAtMs ?? entry.recordedAtMs,
+            updatedAtMs: entry.recordedAtMs,
+            // A completion with no start is a journal whose head was never written;
+            // counting it as one attempt is more honest than reporting zero.
+            attempts: previous?.attempts ?? 1,
+            outcome: entry.outcome,
+        });
+    }
+    const records = order
+        .map((key) => byKey.get(key))
+        .filter((value) => value !== undefined);
+    return summarizeJournalRecords(records, read.damage);
+}
+/** Build the summary views over already-reconstructed records (native or legacy). */
+export function summarizeJournalRecords(records, damage) {
+    const pending = records.filter((record) => record.disposition === 'pending');
+    const unknownOutcome = records.filter((record) => record.disposition === 'unknown-outcome');
+    const blocked = records.filter((record) => record.disposition === 'blocked');
+    const reconciliationRequired = [
+        ...new Set([...pending, ...unknownOutcome].map((record) => record.physicalModemId)),
+    ].sort();
+    return { records, pending, unknownOutcome, blocked, reconciliationRequired, damage };
+}

package/dist/journal/store.d.ts

@@ -0,0 +1,55 @@
+import { type JournalDecodeFailure } from './codec.js';
+import type { JournalEntry } from './entry.js';
+/** Default file mode. `0600` for the same reason the two policy stores use it. */
+export declare const JOURNAL_FILE_MODE = 384;
+/** Where a damaged record was found. Line-based, slot-based, or the whole file. */
+export type JournalDamageLocation = {
+    readonly kind: 'line';
+    readonly line: number;
+    readonly trailing: boolean;
+} | {
+    readonly kind: 'slot';
+    readonly slot: string;
+} | {
+    readonly kind: 'file';
+};
+/** One record that could not be read, reported rather than dropped. */
+export interface JournalDamageRecord {
+    readonly location: JournalDamageLocation;
+    readonly bytes: number;
+    readonly failure: JournalDecodeFailure;
+}
+/** One decoded entry with the 1-based line it came from. */
+export interface JournalLineRecord {
+    readonly line: number;
+    readonly entry: JournalEntry;
+}
+export interface JournalReadResult {
+    readonly entries: readonly JournalLineRecord[];
+    readonly damage: readonly JournalDamageRecord[];
+}
+export interface JournalStore {
+    /** The injected path, echoed back so a caller can report where it recovered from. */
+    readonly path: string;
+    append(entry: JournalEntry): Promise<void>;
+    read(): Promise<JournalReadResult>;
+}
+export interface FileJournalStoreOptions {
+    /** REQUIRED. There is no default and no fallback. */
+    readonly path: string;
+    readonly mode?: number;
+}
+export declare class JournalPathError extends Error {
+    readonly name = "JournalPathError";
+    constructor();
+}
+/**
+ * Decode a whole journal document.
+ *
+ * Exported because the corruption fixtures assert against it directly — proving
+ * the "survivors are kept" property without needing a filesystem to prove it.
+ * Blank lines carry no record and are skipped rather than reported: a trailing
+ * newline is how every line ends, so the final split member is always empty.
+ */
+export declare function decodeJournalText(text: string): JournalReadResult;
+export declare function createFileJournalStore(options: FileJournalStoreOptions): JournalStore;

package/dist/journal/store.js

@@ -0,0 +1,150 @@
+// The append-only journal store. THE PATH IS INJECTED AND HAS NO DEFAULT.
+//
+// This package never learns where a journal lives. The embedding process owns that
+// decision because it owns the filesystem contract: on a CeraLive device the
+// update-surviving partition is the right home, on a bench box a scratch directory
+// is, and in a test a `mkdtemp` directory is. A default here would be a policy this
+// library has no standing to set, and — worse — a default is what turns "the
+// embedder forgot to configure it" into "we silently wrote somewhere plausible".
+// `journal-path-injection.test.ts` fails the build if an absolute path literal ever
+// appears in this directory's executable source.
+//
+// THREE PROPERTIES THIS STORE GUARANTEES, ALL LOAD-BEARING:
+//
+//  1. APPEND-ONLY. There is no verb here that rewrites or truncates the file.
+//     A rewrite is the one operation that can lose a fact that was already
+//     durable, and a journal that can lose a fact answers nothing after a crash.
+//
+//  2. A DAMAGED RECORD NEVER DISCARDS ITS NEIGHBOURS. `read()` decodes every line
+//     independently and returns the survivors alongside a typed damage report.
+//     Stopping at the first bad line — the natural thing a `for` loop with a throw
+//     does — silently truncates the journal to its first corruption, which is
+//     exactly the failure mode this store exists to make impossible.
+//
+//  3. A TORN TRAILING LINE IS CLOSED BEFORE THE NEXT APPEND. A process killed
+//     mid-write leaves a final line with no terminator. Appending straight onto it
+//     would glue the new entry to the garbage and corrupt a SECOND record — one
+//     that was never in flight when the crash happened. The store probes the last
+//     byte once and emits a leading terminator when the file does not end in one,
+//     so the damage stays confined to the record that actually tore.
+import { appendFile, chmod, mkdir, open, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { decodeJournalEntry, encodeJournalEntry } from './codec.js';
+const NEWLINE = 0x0a;
+/** Default file mode. `0600` for the same reason the two policy stores use it. */
+export const JOURNAL_FILE_MODE = 0o600;
+export class JournalPathError extends Error {
+    name = 'JournalPathError';
+    constructor() {
+        super('journal path refused: an explicit, non-empty path must be injected');
+    }
+}
+/**
+ * Decode a whole journal document.
+ *
+ * Exported because the corruption fixtures assert against it directly — proving
+ * the "survivors are kept" property without needing a filesystem to prove it.
+ * Blank lines carry no record and are skipped rather than reported: a trailing
+ * newline is how every line ends, so the final split member is always empty.
+ */
+export function decodeJournalText(text) {
+    const lines = text.split('\n');
+    let lastPopulated = -1;
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        if ((lines[index] ?? '').trim().length > 0) {
+            lastPopulated = index;
+            break;
+        }
+    }
+    const entries = [];
+    const damage = [];
+    for (const [index, raw] of lines.entries()) {
+        if (raw.trim().length === 0)
+            continue;
+        const decoded = decodeJournalEntry(raw);
+        if (decoded.ok) {
+            entries.push({ line: index + 1, entry: decoded.value });
+            continue;
+        }
+        damage.push({
+            location: { kind: 'line', line: index + 1, trailing: index === lastPopulated },
+            bytes: Buffer.byteLength(raw, 'utf8'),
+            failure: decoded.failure,
+        });
+    }
+    return { entries, damage };
+}
+class FileJournalStore {
+    path;
+    #mode;
+    #tail = Promise.resolve();
+    /** Undefined until the first append probes the existing file's final byte. */
+    #terminated;
+    constructor(options) {
+        if (typeof options.path !== 'string' || options.path.trim().length === 0) {
+            throw new JournalPathError();
+        }
+        this.path = options.path;
+        this.#mode = options.mode ?? JOURNAL_FILE_MODE;
+    }
+    append(entry) {
+        // Chained so two concurrent appends cannot interleave, and recovered from so
+        // one failed append does not poison every later one with its rejection.
+        const next = this.#tail.catch(() => undefined).then(() => this.#appendNow(entry));
+        this.#tail = next.catch(() => undefined);
+        return next;
+    }
+    async read() {
+        let text;
+        try {
+            text = await readFile(this.path, 'utf8');
+        }
+        catch (error) {
+            // An ABSENT journal is an empty one — nothing was ever written. Anything
+            // else (permissions, a directory in the way) is reported as damage: a
+            // journal we could not open is not evidence that no mutation was pending.
+            if (error.code === 'ENOENT') {
+                return { entries: [], damage: [] };
+            }
+            return {
+                entries: [],
+                damage: [{ location: { kind: 'file' }, bytes: 0, failure: { code: 'unreadable' } }],
+            };
+        }
+        return decodeJournalText(text);
+    }
+    async #appendNow(entry) {
+        await mkdir(dirname(this.path), { recursive: true });
+        this.#terminated ??= await this.#probeTerminated();
+        const line = `${this.#terminated ? '' : '\n'}${encodeJournalEntry(entry)}\n`;
+        await appendFile(this.path, line, { mode: this.#mode });
+        // chmod AFTER the write, not as an open flag, so the mode holds regardless of
+        // umask — the same reason the usage and FCC policy stores do it this way.
+        await chmod(this.path, this.#mode);
+        this.#terminated = true;
+    }
+    async #probeTerminated() {
+        let handle;
+        try {
+            handle = await open(this.path, 'r');
+        }
+        catch {
+            // No file yet: the first line starts the document, nothing to close.
+            return true;
+        }
+        try {
+            const { size } = await handle.stat();
+            if (size === 0)
+                return true;
+            const tail = Buffer.alloc(1);
+            await handle.read(tail, 0, 1, size - 1);
+            return tail[0] === NEWLINE;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}
+export function createFileJournalStore(options) {
+    return new FileJournalStore(options);
+}

package/dist/location/fix-state.d.ts

@@ -0,0 +1,53 @@
+import type { EpochMillis } from '../domain/index.js';
+import type { FixRead, GnssFix } from '../ports/location.js';
+export interface GnssFixStateConfig {
+    /** How long acquisition may run before the state turns to an honest `no-fix`. */
+    readonly acquireTimeoutMs: number;
+    /** How long a fix stays current before it expires and is dropped. */
+    readonly fixTtlMs: number;
+}
+/**
+ * Defaults chosen against the fleet's own numbers: a cold GNSS start on the
+ * bench modems is a low-minutes affair, so 120 s is long enough to be a fair
+ * attempt and short enough that a missing antenna is reported inside a support
+ * call rather than after one. A fix older than 30 s is not "current" on a moving
+ * vehicle, which is the only context this display has.
+ */
+export declare const DEFAULT_FIX_STATE_CONFIG: GnssFixStateConfig;
+export type NoFixReason = 'acquire-timeout' | 'reported-no-fix' | 'fix-expired';
+export type GnssFixState = {
+    readonly kind: 'off';
+} | {
+    readonly kind: 'acquiring';
+    readonly since: EpochMillis;
+} | {
+    readonly kind: 'no-fix';
+    readonly since: EpochMillis;
+    readonly reason: NoFixReason;
+} | {
+    readonly kind: 'fix';
+    readonly fix: GnssFix;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+export type GnssFixEvent = {
+    readonly kind: 'gnss-enabled';
+    readonly at: EpochMillis;
+} | {
+    readonly kind: 'gnss-disabled';
+} | {
+    readonly kind: 'read';
+    readonly at: EpochMillis;
+    readonly read: FixRead;
+} | {
+    readonly kind: 'tick';
+    readonly at: EpochMillis;
+};
+export declare const GNSS_OFF: GnssFixState;
+/** A fix is reachable ONLY here, and only while the state actually holds one. */
+export declare function renderableFix(state: GnssFixState): GnssFix | undefined;
+/** True while a bounded wait is legitimately in progress — the only spinner state. */
+export declare function isAcquiring(state: GnssFixState): boolean;
+/** Pure, total transition. Every exit from `fix` drops the coordinates. */
+export declare function advanceGnssFixState(state: GnssFixState, event: GnssFixEvent, config?: GnssFixStateConfig): GnssFixState;